Payments

Overview

A payment refers to an individual attempt to process a charge against a specific payment method. Each payment attempt is a distinct operation that may succeed or fail independently. A single transaction can involve multiple payment attempts if retries are required.

For more details on initiating payments, refer to the Initiate Payment API.

Payment Attempts Explained

• Single Attempt: A simple one-time payment with no retries.
• Multiple Attempts: If a payment fails, the platform automatically retries using alternative processors or payment methods (if configured).

Payment Attempt States:

1. Initiated: Payment request is sent to the payment processor.
2. Pending: Payment is under review or awaiting customer action (e.g., 3D Secure).
3. Authorized: Payment was approved but not yet captured.
4. Captured: Funds have been transferred from the customer.
5. Failed: Payment attempt failed, and the platform may retry.
6. Refunded: Payment was refunded (full or partial).

For more information on payment states, see the Payments API reference.

Payment Methods

The platform supports various payment methods, including:

• Credit/Debit Cards: Securely processed through tokenized transactions.
• Bank Transfers: Supports real-time and batch transfers.
• Mobile Money
• Digital Wallets: PayPal, Apple Pay, and others.

To view available payment methods, check the Get Available Payment Methods API.

Example Payment Payload

1
{
2
  "attemptId": "attempt_01",
3
  "transactionId": "1234567890",
4
  "processor": "Processor_A",
5
  "status": "captured",
6
  "amount": 10000,
7
  "currency": "USD",
8
  "paymentMethod": {
9
    "type": "card",
10
    "cardDetails": {
11
      "brand": "Visa",
12
      "last4": "4242",
13
      "expiryMonth": "12",
14
      "expiryYear": "2026"
15
    }
16
  },
17
  "timestamp": "2024-10-17T12:05:00Z"
18
}

For the full schema, refer to the Payment Initiate Request Schema.

Handling Payment Failures

The platform retries failed payment attempts automatically. Merchants can configure retry rules to maximize success rates. In cases where retries are exhausted, a webhook notification will be sent to the merchant for further action.

For more details on handling failures, see the Error Response Schema.

Payment Capture and Refunds

• Capture: Payments must be captured to finalize the transfer of funds.
• Refunds: Payments can be refunded (partially or fully) based on merchant policies.

To refund a payment, use the Create Refund API. Refunds are issued against a session and accept a refundValue object (minorAmount plus ISO 4217 currency); see Full and Partial Refunds for details.

Cancelling a Payment

Cancellation is split across two endpoints depending on whether you want to cancel an entire checkout session or a single transaction.

Cancel a session

POST /checkout/session/cancel takes a sessionId and cancels the whole session. The session is locked against any further payment attempts, and every in-flight transaction linked to the session is cancelled in the same call. Transactions already in a terminal state (settled, failed, refunded) are not affected.

If one of those in-flight transactions is being processed by a provider that does not support cancelling an in-progress transaction, the session enters the PENDING_CANCELLATION state. While in this state:

• No further payment attempts can be initiated against the session.
• The session is not considered fully cancelled — it only moves to CANCELLED once the outstanding transaction reaches its own terminal state.

The response returns the session’s resulting status (CANCELLED or PENDING_CANCELLATION), the transactions that were successfully cancelled in cancelledTransactionIds, and any unstoppable in-flight transactions in pendingTransactionIds.

Clean cancel — every in-flight transaction was cancellable, so the session reaches CANCELLED immediately:

1
{
2
  "sessionId": "01951c8a-7c3d-7e1f-9d4a-2b3c4d5e6f70",
3
  "status": "CANCELLED",
4
  "message": "Session cancelled. 1 in-flight transaction was cancelled as part of this call.",
5
  "cancelledTransactionIds": ["01951c8a-8b4c-7d2a-8f1e-5d6c7b8a9e10"],
6
  "pendingTransactionIds": []
7
}

Pending cancellation — one of the in-flight transactions belongs to a provider that does not support in-process cancellation. The session is locked but not yet terminal; it will move to CANCELLED once the listed transaction reaches its own terminal state on the rail:

1
{
2
  "sessionId": "01951c8a-7c3d-7e1f-9d4a-2b3c4d5e6f70",
3
  "status": "PENDING_CANCELLATION",
4
  "message": "Session locked. Awaiting terminal state on 1 in-flight transaction whose provider does not support in-process cancellation.",
5
  "cancelledTransactionIds": ["01951c8a-8b4c-7d2a-8f1e-5d6c7b8a9e10"],
6
  "pendingTransactionIds": ["01951c8a-ad6f-7b1c-a2d3-7f8e9d0c1b32"]
7
}

Cancel a transaction

POST /payment/{transactionId}/cancel cancels a single transaction by its id. No session id is required — the transaction id is sufficient. The transaction’s session and any other transactions on it remain active.

A transaction can only be cancelled while it is in a non-terminal state and while its originating provider supports cancelling an in-progress transaction. Otherwise the call returns 409.

Security and Compliance

• PCI Compliance: Merchants must ensure PCI compliance when handling card data directly.
• 3D Secure Authentication: The platform supports 3D Secure to reduce fraud.

For more information on security, refer to the Security and Compliance Documentation.

External Resources

For a complete list of API operations and schemas, visit the API Documentation.