Skip to main content
Version: 4.0.2

End-to-End Payment Flow

This guide describes a complete Charge SDK payment integration from checkout to settlement: what your frontend and backend are each responsible for, when to call the Charge API, when to mount the Charge SDK, and how to confirm the result of a payment.

Integration at a glance​

ComponentOwned byResponsibilities
Checkout frontendMerchantRequests checkout from your backend, mounts the Charge SDK, handles the post-payment redirect
BackendMerchantAuthenticates with the Charge API, creates orders, receives webhooks, retrieves and stores payment results
Charge SDKDataMeshRenders the payment UI, collects payment details (keeping you outside PCI scope), processes the payment
Charge APIDataMeshOrder creation, charge processing, charge status retrieval
WebhooksDataMeshPush payment and settlement results to your backend
Settlement APIDataMeshSettlement reporting for finance/ERP reconciliation (optional)

Before you start​

During onboarding, DataMesh provides the credentials your integration uses:

CredentialUsed byPurpose
jwt_public_keyBackendAuthenticates with the Charge API. Store securely; never expose in client-side code.
jwt_secretBackendAuthenticates with the Charge API. Store securely; never expose in client-side code.
merchant_idFrontendYour unique merchant identifier, used when mounting the Charge SDK. This is the same value as your service_id.
config_idFrontendIdentifies the payment configuration (allowed origins, enabled payment methods, redirect URLs) used to construct the Charge SDK. Environment-specific — use the correct config_id for staging vs production.
public_keyFrontendAuthenticates the Charge SDK mount.

You must also provide DataMesh with:

  • A redirect URL for your checkout result page — either separate success and failure URLs, or a single result URL. Must be HTTPS in production. Configured per config_id in the Merchant Portal.
  • A webhook endpoint on your backend — must be HTTPS in production and reachable from the internet. Configured in the Merchant Portal.

See Authentication for how to construct the Charge API JWT.

Payment flow​

Step by step​

  1. Customer reaches your checkout. Your frontend asks your backend to create a checkout session.
  2. Backend authenticates with the Charge API. Create a JWT from your jwt_public_key and jwt_secret — see Authentication.
  3. Backend creates the order with POST /order_token. Set your_order_reference (string, max 32 characters) to your own order ID — it appears as the searchable Merchant Reference field in the Merchant Dashboard. If your finance systems reconcile through the Settlement API, also add the same value as a merchant_order_ref key/value pair in your_order_details; these key/value pairs are returned in the Settlement API transaction notes.
  4. Backend returns the order_id from the response to your frontend.
  5. Frontend mounts the Charge SDK using the dynamic order_id plus the static merchant_id, config_id, and public_key. The payment UI renders inside the container element you nominate, showing the payment methods enabled for your merchant configuration.
  6. The customer pays. The Charge SDK collects payment details and processes the payment with DataMesh and the payment service provider. Your systems never touch the payment details.
  7. The Charge SDK redirects the customer to your configured result URL with query parameters status (completed on success, otherwise the charge status), charge_id, order_id, and config_id. Treat this redirect as display-only — use it to show the customer a result page, not to update your records (the customer can close the window, lose connectivity, or never return).
  8. Your webhook receives the result. DataMesh POSTs a charge webhook to your backend as the charge changes status. Delivery is attempted up to 7 times at increasing intervals until your endpoint responds 200 OK — so respond 200 promptly, and handle redelivery idempotently.
  9. Backend confirms the charge. On a completed webhook, extract the charge_id and call GET /charge/{charge_id}. The payment is successful when status.status is completed. Do not treat any other status — or the redirect alone — as confirmation of payment.
The webhook is the source of truth

Confirm payments from the webhook plus GET /charge/{charge_id} on your backend, never from frontend events or the redirect. Frontend signals are best-effort: they fail when the customer closes the payment window, loses network connectivity, or abandons the flow mid-payment.

Settlement (optional)​

If your finance or ERP systems reconcile settlements, two further integrations are available:

  1. A settlement webhook fires as a settlement changes status (for example settled). The payload contains the settlement_id.
  2. Query the Settlement API with that settlement_id for the settlement header (gross amount, fees, tax, accountingToken) and the individual transactions it contains. Each transaction carries your merchant_order_ref / merchant_customer_ref values in its notes, linking settlements back to your orders.

See the Settlement API reference for endpoints and payloads.

Next steps​