Recurring payment (API-based)
Recurring use of a card or bank instrument means you verify it once through a setup session, then reuse the same payment method (paymentMethodGid) across many payment sessions (subscriptions, installments, repeat purchases—whatever your product schedules).
At a high level:
- Token → customer → payment method (same first steps as One-time payment).
- Setup session — Swirepay verifies the instrument already attached via token/payment method for saved / off-session reuse (see Create setup session).
- After setup completes successfully (for example status VERIFIED), charge repeatedly with
POST /v1/payment-sessionusing thatpaymentMethodGid.
If you skip setup and only ever run a single payment session, that flow behaves like a one-off charge; the instrument is not treated as eligible for recurring reuse until it has gone through setup verification.
Why setup session matters
A payment method created from a token alone is not automatically reusable for ongoing charges.
| Instrument path | Typical use |
|---|---|
| Payment session only (no setup session) | Typically one successful charge per vaulted instrument path your integration uses; do not rely on charging the same paymentMethodGid again until setup verification has succeeded. |
| Setup session completes successfully | The method is verified for recurring-style reuse. You may create multiple payment sessions against the same paymentMethodGid. |
In short: a payment method that does not complete setup session verification cannot be used for more than one payment session when you need repeat charges on that saved instrument—run setup session first, then reuse the same paymentMethodGid across multiple payment sessions.
Partner-specific routing (x-destination-account) is covered in Partner integration; marketplace platforms sometimes vault instruments on the parent account first—see that guide.
How recurring differs from one-time
After you have a paymentMethodGid, do not assume it is ready for recurring debits. You must create a setup session so Swirepay can verify and register the instrument for off-session / recurring use. One-time flows skip this and go straight to Create payment session.
| Stage | One-time | Recurring |
|---|---|---|
| Token, customer, payment method | Same as One-time guide | Same |
| Next step | Payment session | Setup session |
| Then | Done when session succeeds | Same payment method reused in further payment sessions, plus any subscription/recurring APIs your product uses |
Setup session (recurring)
POST /v1/setup-session
Use your secret key. Pass paymentMethodGid, currencyCode, description, paymentMethodType (for example ["CARD"]), and confirmMethod (for example AUTOMATIC) as required by your integration.
The response includes setup status (for example VERIFIED when successful) and a ssClientSecret for any client-side completion steps your integration uses. Full request and response schemas: Create setup session.
Partner integration (submerchants)
Partners often attach customers and instruments to a submerchant using x-destination-account on token, customer, payment method, setup session, and payment session—see Partner integration.
Alternatively, partners may vault customers and payment methods on the parent account first (no header), then pass x-destination-account only on payment session when settling against a submerchant. That pattern is documented under Saved instruments on the partner account in Partner integration.
See also
- One-time payment — shared steps (token, customer, payment method) and PCI / hosted alternatives
- Partner integration — marketplace routing, parent-vault patterns, and
x-destination-account - Guides introduction
- API reference: Setup session, Payment session