Direct integration (one-time charge)

This guide describes the REST API journey for integration partners who want a whitelabel, server-driven card or ACH flow under Payment Center: collect payment details on your pages, tokenize via Swirepay, then charge using token → customer → payment method → payment session.

For the alternative where Swirepay hosts checkout on a payment page, see Hosted Payment Link.

One-time charges and recurring charges share the same first steps (token → customer → payment method). They diverge after the payment method exists: one-time uses a payment session; recurring requires a setup session so the saved payment method can be used for future charges. For the recurring-only continuation, see Recurring payment.

Where to find request/response details

Field-level documentation, try-it-out, and full schemas live in Payment Center API reference: Token, Customer, Payment method, Setup session, Payment session.

If you integrate as a partner onboarding submerchants, send the optional x-destination-account header (submerchant sp-account-id) on token, customer, payment method, and payment session requests when acting on behalf of a submerchant—omit it for your own merchant account. See Partner integration.

API-based payments and PCI scope

When your application collects full card numbers and calls Swirepay’s APIs directly, your program typically falls under PCI SAQ A (or a comparable assessment), depending on how card data is collected and transmitted. Swirepay can help you validate the right compliance path.

If you do not want to capture or transmit full PAN on your own checkout, use Hosted Payment Link or another hosted surface instead — see API reference Payment Link.

One-time vs recurring at a glance

Step	One-time charge	Recurring (reuse same payment method)
Tokenize card	Yes — Create token	Same
Customer	Recommended; required to attach a reusable payment method — Create customer	Same
Create payment method	Yes — Add payment method	Same
Setup session	Not used for a simple one-off charge	Required — Create setup session verifies/saves the instrument for recurring use
Charge	Create payment session with amount	After setup, use your recurring APIs/schedules as documented in Recurring payment and in API reference

Important: A payment method you “collected” for a one-time payment is not automatically eligible for recurring charges. To use the same payment method for recurring, you must run it through a setup session (and satisfy customer/payment-method requirements). See Recurring payment.

End-to-end journey (one-time)

Base URL for all paths below:

https://api.swirepay.com

1. Create token (card) — public key

Call POST /v1/token from your frontend (or a environment that may see card data), using your publishable API key. This tokenizes the card; tokens are short-lived (for example 15 minutes) and should be passed to your backend, which then creates the payment method with a secret key.

Headers

• x-api-key: your public key (for example pk_test_…)

Example request body

{
  "type": "CARD",
  "card": {
    "number": "4242424242424242",
    "cvv": "123",
    "expiryMonth": 12,
    "expiryYear": 2028,
    "name": "Cardholder Name"
  },
  "postalCode": "95015",
  "paymentMethodBillingAddress": {
    "street": "2001 Langly Drive",
    "city": "Los Angeles",
    "state": "CA",
    "countryCode": "US"
  },
  "countryCode": "US"
}

Example response (trimmed)

Use the token gid from entity.gid as the token value when creating a payment method.

{
  "status": "SUCCESS",
  "responseCode": 200,
  "message": "OK",
  "entity": {
    "gid": "token-…"
  }
}

Full payload: Create a token.

2. Create customer (recommended)

For flows that attach a card to a customer (including most saved-instrument and recurring paths), create a customer first.

POST /v1/customer

Headers

• x-api-key: your secret key (for example sk_test_…)
• x-destination-account: the affiliated account GID (for example account-…)

Example request body

{
  "name": "John Wick",
  "email": "john@example.com"
}

Example response (trimmed)

Store entity.gid as customerGid for the payment method call.

{
  "status": "SUCCESS",
  "responseCode": 200,
  "message": "OK",
  "entity": {
    "gid": "customer-…"
  }
}

Full payload: Create a customer.

3. Create payment method

POST /v1/payment-method

Headers

• x-api-key: secret key only

Example request body

{
  "token": "token-…",
  "type": "TOKEN",
  "customerGid": "customer-…"
}

Use the token gid from step 1 and customer gid from step 2.

Example response (trimmed)

Use entity.gid as paymentMethodGid when creating a payment session (one-time) or setup session (recurring).

{
  "status": "SUCCESS",
  "responseCode": 200,
  "message": "OK",
  "entity": {
    "gid": "paymentmethod-…"
  }
}

Full payload: Add payment method.

4. One-time charge: payment session

POST /v1/payment-session

Create a session with the amount (in cents), currency, paymentMethodGid, capture/confirm settings, and optional receipt metadata.

Headers

• x-api-key: secret key

Example request body

{
  "receiptEmail": "customer@example.com",
  "receiptSms": "+14165551234",
  "currencyCode": "USD",
  "description": "One-time purchase",
  "paymentMethodType": ["CARD"],
  "applicationFee": 200,
  "confirmMethod": "AUTOMATIC",
  "captureMethod": "AUTOMATIC",
  "amount": 2000,
  "paymentMethodGid": "paymentmethod-…",
  "meta": {
    "orderId": "09248297353"
  }
}

Example response (trimmed)

Check entity.status (for example SUCCEEDED), amountReceived, and receiptNumber. Use psClientSecret when your client needs to complete any required next actions (if applicable for your integration).

{
  "status": "SUCCESS",
  "responseCode": 200,
  "message": "OK",
  "entity": {
    "gid": "paymentsession-…",
    "status": "SUCCEEDED",
    "amount": 2000,
    "amountReceived": 2000,
    "receiptNumber": "…",
    "psClientSecret": "paymentsession-…_…"
  }
}

Full payload: Create a payment session.

Flow summary

Shared path: POST /v1/token (public key) → POST /v1/customer (secret key) → POST /v1/payment-method (secret key).

Then:

• One-time: POST /v1/payment-session with amount and paymentMethodGid.
• Recurring: POST /v1/setup-session with paymentMethodGid, then recurring/subscription APIs — see Recurring payment.

See also

• One-time payment overview — compare Direct integration vs Hosted Payment Link
• Hosted Payment Link
• Recurring payment — setup session and using the same payment method for recurring
• Guides introduction
• Payment Center API: Payment session, Setup session