DEVELOPER WORKSPACE

Plan the integration before you write the first request

A practical overview of how payment integrations are usually organized—from mapping the flow to handling outcomes and operational events.

See the integration path

PAYMENT REQUEST FLOWREFERENCE / 01

01POST/payment-intents

02VALIDATE REQUEST

03RETURN STATUS

CONCEPTUAL EXAMPLEJSON

Illustrative integration guide

The examples and endpoint shapes on this page are conceptual. They are not a published API contract, credentials, or a production integration guide.

INTEGRATION PATH

A clear sequence for implementation

Map the use case

Identify who initiates the payment, which systems participate and what a successful outcome means to your product.

Choose the workflow

Decide how checkout, collection, risk review and payment status should connect to your customer journey.

Connect events

Plan how your application will receive status changes and how it will reconcile them with internal records.

Review edge cases

Define how your team will handle retries, timeouts, duplicate notifications and manual review.

PLANNING CHECKLIST

Integration concepts

Use these topics as a checklist when defining a future API specification with your implementation team.

Payment intent

The business context and amount associated with a payment attempt.

Idempotency

A request identifier that helps an integration safely handle repeated submissions.

Payment status

A state that your application should reconcile with its own order lifecycle.

Webhook event

An event notification that should be authenticated, acknowledged and processed safely.

Reconciliation

A process for comparing payment records with your internal ledger or order system.

Error handling

A deliberate response to validation failures, network issues and uncertain outcomes.

ILLUSTRATIVE JSON

A conceptual payment request

This JSON shape illustrates common fields a payment workflow might need. Confirm the actual schema and authentication method with the service specification before implementation.

Before going live

Confirm endpoint URLs, authentication, supported currencies, event signatures, retry rules and settlement behavior with the final integration documentation.

payment-request.jsonILLUSTRATIVE

{
  "reference": "ORDER_REFERENCE",
  "amount": {
    "value": "AMOUNT_TO_CONFIRM",
    "currency": "CURRENCY_CODE"
  },
  "returnUrl": "YOUR_CHECKOUT_RETURN_URL",
  "metadata": {
    "source": "YOUR_APPLICATION"
  }
}

CONFIRM FIELDS IN FINAL SPECapplication/json

PLAN AN INTEGRATION

Discuss an integration

Share your use case and the systems involved so the integration scope can be defined clearly.

Talk to our team