Skip to main content

Partner integration (submerchants)

Swirepay partners can onboard submerchants (your customers’ merchant accounts)—for example in a marketplace where buyers pay different sellers you onboard as submerchants.

Typical flows:

  • Per-submerchant collections: Create customers, tokens, payment methods, setup sessions, and payment sessions scoped to each seller by passing x-destination-account with that seller’s sp-account-id.
  • Shared wallet on the partner (parent) account: Keep one customer database and saved payment methods under your partner Swirepay account, then route settlements to the right submerchant only when you charge—see Saved instruments on the partner account.

Core REST steps still match One-time payment and Recurring payment: token → customer → payment method → setup session (for reusable instruments) → payment session(s). For one-time flows that use hosted payment links instead, see Hosted Payment Link and send x-destination-account on payment link create/get/verify when scoping to a submerchant.

What changes for partners is an optional HTTP header that routes requests to a submerchant account when you choose to use it.

Submerchant onboarding​

Seamless boarding (Connect)​

Redirect the user to Swirepay Connect so they can complete onboarding and become your submerchant:

https://secure.swirepay.com/connect?key=<BASE64_ENCODED_PUBLIC_KEY>&redirectUrl=<YOUR_ENCODED_REDIRECT_URL>
  • key: Base64-encoded public API key (pk_test_… / pk_live_…), not the raw key string.
  • redirectUrl: Where Swirepay sends the user after onboarding (must match what you configure for your integration).

After completion, Swirepay redirects to your URL with sp-account-id in the query string (for example https://your-app.example/?sp-account-id=account-fdb397352f0448588bc94bb3967dc41d). Persist this value—it identifies the submerchant for API calls.

Use keys from your dashboard or those provided by your Swirepay relationship manager. Do not embed example or third-party keys in production apps.

Optional header: x-destination-account​

When your integration acts for a submerchant, include:

x-destination-account: <sp-account-id>

Replace <sp-account-id> with the value from Connect (or from manual onboarding)—for example account-fdb397352f0448588bc94bb3967dc41d.

ScenarioHeader
Charges or resources for a submerchantInclude x-destination-account with that submerchant’s sp-account-id.
Charges for the partner’s own Swirepay accountOmit this header (same APIs as a direct merchant).

Apply the header when you intend the operation to execute in the submerchant’s account. Parameters are documented on each endpoint in the Payment Center API reference.

Saved instruments on the partner account​

Some platforms want one buyer identity and one vaulted card that can fund purchases across many submerchants, without collecting card details again for each seller.

You can do this by creating the customer, token, payment method, and setup session without x-destination-account, so customers and verified instruments live under your partner (parent) Swirepay account.

Later, when an end-customer buys from seller B, create payment sessions with x-destination-account set to seller B’s sp-account-id, reusing the same paymentMethodGid (and related customer identifiers your integration ties together). That way settlement can attribute to seller B while the sensitive onboarding and recurring readiness (setup session) happened once at the partner level—avoiding duplicate collection per submerchant.

Confirm settlement and reporting behavior with your Swirepay integration contact so it matches your commercial agreement.

Partner flow options (submerchant vault vs parent vault)​

Option A — Everything under the submerchant

Follow One-time (Direct integration) / Recurring steps with x-destination-account on token, customer, payment method, setup session (when you need reusable instruments—see Recurring payment), and each payment session. For Hosted Payment Link, send the same header on create, get, and verify payment link calls when the link is for a submerchant.

Option B — Vault on partner, charge submerchant

  1. Vault: Customer → token → payment method → setup session without x-destination-account (partner account holds the saved, verified instrument).
  2. Charge: Payment session with x-destination-account for whichever submerchant should receive/settle that payment.

For simple one-time charges without recurring reuse, Option A alone may suffice; Recurring explains when setup session is mandatory for multiple charges on the same method.

Hosted Payment Link uses the Payment Center Create payment link / Verify payment link APIs; see Hosted Payment Link in the guides.

Payment Checkout and other checkout-page endpoints are not part of this site’s generated OpenAPI—see your Partner Integration Kit or Swirepay contact for those URLs and payloads.

See also​

On this page