Skip to main content

Hosted Payment Link (one-time)

This flow minimizes payment UI work on your site: your backend creates a payment link via API, you send the customer to Swirepay’s hosted checkout (entity.link), and after payment Swirepay redirects them back to your redirectUri. You then verify status server-side before showing success or failure.

It aligns with the Payment Links pattern described in Swirepay’s integration materials (hosted checkout vs capturing PAN on your domain — see internal reference Swirepay PG Merchant Integration Kit): notifications (SMS/email), optional expiry, verification APIs, and optional server callbacks.

For token → payment method → payment session on your pages instead, see Direct integration.

At a glance​

  1. POST /v1/payment-link with amount (cents), currency, description, payer hints (customer object or customerGid), redirectUri, and optional serverCallbackUrl.
  2. Read entity.link from the response and redirect the payer’s browser there (hosted payment page for card or ACH as configured).
  3. After checkout, Swirepay redirects to redirectUri (typically with payment-link context you can read server-side).
  4. Call GET /v1/payment-link/{gid}/verify from your backend (with the payment link GID) to confirm status and inspect paymentSession when paid.

Full API schemas and try-it-out: Create payment link, Get payment link, Verify payment link.

Partner integrations​

When acting on behalf of a submerchant, send the optional x-destination-account header with that merchant’s sp-account-id on:

  • POST /v1/payment-link (create)
  • GET /v1/payment-link/{gid} (retrieve)
  • GET /v1/payment-link/{gid}/verify (verify)

Omit the header when the operation applies to your own Swirepay account. Same semantics as Partner integration for REST APIs.

POST /v1/payment-link

Headers

  • x-api-key: secret key (recommended for server-side creation).
  • x-destination-account: optional — affiliate account GID for partner/submerchant context (see above).

Body (common fields)

FieldPurpose
amountAmount in cents
currencyCodeFor example USD
descriptionShown on hosted checkout and receipts
paymentMethodTypeFor example ["CARD"], ["ACH"], or both
redirectUriHTTPS URL to send the payer after payment (GET redirect)
customerNew customer { name, email, phoneNumber } or use customerGid for an existing customer
notificationTypeHow Swirepay notifies the payer (see API schema)
serverCallbackUrlOptional HTTPS URL for Swirepay to POST a server-to-server completion payload
expiresAtOptional expiration for the link

Example shape (new customer):

{
  "amount": 5000,
  "currencyCode": "USD",
  "paymentMethodType": ["CARD", "ACH"],
  "redirectUri": "https://merchant.example.com/pay/return",
  "description": "Invoice #1234",
  "customer": {
    "email": "payer@example.com",
    "name": "Jane Doe",
    "phoneNumber": "+14155550100"
  },
  "serverCallbackUrl": "https://merchant.example.com/webhooks/payment-link"
}

Response: entity.link is the hosted URL to open for the payer (environment-specific host). Store entity.gid as the payment link identifier for verification calls.

Redirect the payer​

Send the customer to entity.link (302/redirect from your app or render as “Pay now”). They complete authentication and payment on Swirepay-hosted UI — you do not collect PAN in your checkout.

After redirect — verify before UX confirmation​

Browser redirects alone are not sufficient for reconciliation — always verify server-side.

GET /v1/payment-link/{gid}/verify

  • Same gid from create response (payment link GID).
  • Pass x-destination-account when verifying on behalf of a submerchant.

Interpret entity.status (for example ACTIVE vs PAID) and whether entity.paymentSession is populated with finalized payment session details when the charge succeeded.

See Verify payment link for response nuances (pending vs complete examples).

Optional: server callback (serverCallbackUrl)​

If you configure serverCallbackUrl on create, Swirepay can POST JSON to your endpoint after successful processing (similar to webhook-style notifications described in broader integration kits). Treat callbacks as supplementary to verify — always reconcile using verify or official webhooks as appropriate for your deployment.

For webhook semantics (headers, signing) for other event types, see Webhook delivery & payloads and Webhooks.

Operational comparisons (hosted vs checkout)​

Hosted Payment Link vs Payment Checkout product differences (notifications, expiry behavior, verification APIs) are summarized in merchant integration references and product docs — choose based on whether you need multi-channel payer notifications and mandatory expiry policies.

See also​

On this page