Save Cards & Charge Later

Two ways to use a saved card

// Save the cardpaymentMethodUsage: 'off_session'// Charge itinitiator: 'merchant'

// Save the cardpaymentMethodUsage: 'on_session'// Charge itinitiator: 'customer'

Want to see a whole flow for a real business first? Try Use cases.

Implementation

Your server uses the same merchant credentials for checkout, saved cards, and later charges.

const session = await tapaya.checkout.sessions.create({
	mode: 'embedded',
	merchantOrderId: 'order-42',
	amount: 1200,
	currency: 'EUR',
	customerReference: 'buyer-42',
	savePaymentMethod: 'optional',
	paymentMethodUsage: 'off_session',
}, { idempotencyKey: 'order-42:initial' })

const renewal = await tapaya.payments.create({
	merchantOrderId: 'sub-42-2026-11',
	amount: 990,
	currency: 'EUR',
	paymentMethodId: 'pm_7Hq2x9LmR4',
	initiator: 'merchant',
	merchantInitiatedReason: 'recurring',
}, { idempotencyKey: 'sub-42-2026-11' })

Save Apple Pay and Google Pay

Wallets use the same fields. To charge an Apple Pay card later, also pass a walletAgreement, which the native sheet shows to the customer:

const walletAgreement = {
	type: 'recurring' as const,
	description: 'Pro plan',
	managementUrl: 'https://shop.example/account/billing',
	recurring: { amount: 990, interval: 'month' as const, intervalCount: 1 },
}

• Pass it on the server and as cardSaving.walletAgreement in the browser.
• managementUrl must use HTTPS on an allowed checkout website.
• For top-ups, use type: 'automatic_reload' with automaticReload: { amount, thresholdAmount }, in minor units.
• Without an agreement, Apple Pay is hidden when saving for later charges.

Saved wallet methods expose card.wallet.type and card.wallet.deviceBound, and support merchant-initiated charges only. A device-bound method can stop working after the customer changes device.

Check a card without charging it

For free trials and bookings, save the card with a €0 verification. Use a unique order reference and required saving:

const setup = await tapaya.payments.create({
	merchantOrderId: 'setup-buyer-42',
	amount: 0,
	currency: 'EUR',
	customerReference: 'buyer-42',
	savePaymentMethod: 'required',
	paymentMethodUsage: 'off_session',
}, { idempotencyKey: 'setup-buyer-42:initial' })

Pass setup.clientSecret to the normal embedded form. Hosted sessions also accept a zero amount with required saving. Cards, Apple Pay, and Google Pay all work, without shippingOptions. For wallets, pass wallets: { amount: 0, currency: 'EUR' } and the matching saving policy; Apple Pay still needs its agreement. Later charges need a positive amount.

Hold, capture, and refund

To hold funds first, as a hotel or rental does, add captureMethod: 'manual'. authorized means the amount is held; capture it before authorizationExpiresAt.

const hold = await tapaya.payments.create({
	merchantOrderId: 'stay-310',
	amount: 20000,
	currency: 'EUR',
	paymentMethodId: 'pm_7Hq2x9LmR4',
	initiator: 'merchant',
	merchantInitiatedReason: 'unscheduled',
	captureMethod: 'manual',
	allowIncrementalAuthorization: true,
}, { idempotencyKey: 'stay-310' })

// After a server read confirms authorization, increase the hold by EUR 50.
await tapaya.payments.increment(hold.id, { amount: 5000 }, {
	idempotencyKey: 'stay-310:extra-night',
})
await tapaya.payments.capture(hold.id, { amount: 18000 }, {
	idempotencyKey: 'stay-310:checkout',
})

To refund a Hosted Checkout payment, pass the session's paymentReference as the payment ID. Read a refund until status is succeeded or failed; pending is unresolved and holds back its amount. Use a separate idempotency key for each create, increment, capture, cancel, or refund, and reuse it with the same body after a lost response. Track amountAuthorized, amountCaptured, and amountRefunded on server reads.

Manage saved cards

const page = await tapaya.paymentMethods.list({
	customerReference: 'buyer-42',
	limit: 25,
})
const method = await tapaya.paymentMethods.get('pm_7Hq2x9LmR4')
await tapaya.paymentMethods.update(method.id, { expMonth: 12, expYear: 2028 })
await tapaya.paymentMethods.delete(method.id)

• Lists return { data, nextCursor }. Pass cursor: page.nextCursor for the next page while it is not null. Filter wallet by none, apple_pay, or google_pay.
• Updates accept expMonth, expYear, cardholderName, and billingAddress. Omitted and null fields stay unchanged. A card saved through Apple Pay or Google Pay cannot be updated and returns 409; the wallet keeps it current.
• Deleting a method stops future charges and keeps past payments. Deleting it again returns the same confirmation.
• Always check that the requested method belongs to the signed-in customer and merchant.