Payments¶

Payment Method¶

A Payment transaction allows merchants to collect funds from a customer using alternative payment methods such as Open Banking, UPI, wallets, bank transfers, or QR codes. Unlike card-based transactions that use the /api/transactions/authorize endpoint, payments are initiated via a dedicated /api/transactions/payment endpoint with a simplified request structure.

Payments are processed asynchronously — the transaction may initially return a PENDING status or a redirect URL, with the final result delivered via webhook.

Key Characteristics¶

Alternative Payment Methods
- Payments support non-card payment methods: Open Banking, UPI, Wallets, Bank Transfer, and QR Code.
- The payment method is specified as a simple string in the method field — no structured payment data object is required.
Fixed Transaction Type
- The transaction type is always PAYMENT. Unlike the authorize endpoint, there is no transaction_type field to set.
No Card Data or Encryption
- Payment requests do not include card data. No encryption is required.
- The browser_info field is not required.
Redirect-Based Flow
- Most payment methods involve a redirect to a third-party provider (bank, wallet app, QR page) where the customer completes the payment.
- The API response will typically include a redirect object with the URL to redirect the customer.
Terminal ID Specification
- The terminal_id must be specified in the request. The terminal must be configured to support payment transactions (feature: TRX_TYPE_PAYMENT).
Asynchronous Processing
- Payments are typically processed asynchronously. The initial API response may return a PENDING status or a redirect.
- The final transaction status is delivered via a Transaction Processed Webhook.
- Always verify the final status using the Transaction Status API.

Supported Payment Methods¶

Method	Value	Description
Open Banking	`OPEN_BANKING`	Bank-initiated payment via Open Banking APIs
UPI	`UPI`	Unified Payments Interface (India)
Wallets	`WALLETS`	Digital wallet payments
Bank Transfer	`BANK_TRANSFER`	Direct bank transfer
QR Code	`QR_CODE`	QR code-based payment

Request Requirements¶

Field	Required	Notes
`terminal_id`	Yes	Must support payment transactions (`TRX_TYPE_PAYMENT`)
`reference`	Yes	Unique payment reference per terminal (max 80 chars). Idempotent — duplicate references with the same amount/currency will return the existing transaction.
`method`	Yes	Payment method type: `OPEN_BANKING`, `UPI`, `WALLETS`, `BANK_TRANSFER`, or `QR_CODE`
`currency`	Yes	ISO 4217 currency code (e.g., `EUR`, `USD`, `THB`)
`amount`	Yes	Amount in minor units (e.g., `10000` = 100.00 EUR)
`description`	No	Human-readable payment description (max 100 chars)
`customer`	No	Customer details (name, email, address, etc.)
`country`	No	ISO 3166-1 alpha-2 country code (e.g., `TH`, `ID`, `IN`)
`customer_ip`	No	Customer IP address (defaults to request IP)
`metadata`	No	Arbitrary key-value metadata
`return_url`	No	URL to redirect after successful payment
`error_url`	No	URL to redirect after failed payment
`cancel_url`	No	URL to redirect after canceled payment
`options`	No	Provider-specific or payment-type-specific options

Processing Flow¶

sequenceDiagram
    participant Customer
    participant Merchant
    participant Gateway
    participant Provider

    Customer->>Merchant: Select payment method
    Merchant->>Gateway: POST /api/transactions/payment
    Gateway->>Gateway: Validate request & terminal
    Gateway->>Gateway: Resolve payment provider
    Gateway->>Provider: Initiate payment

    alt Redirect Required
        Provider-->>Gateway: Redirect URL
        Gateway-->>Merchant: Response with redirect
        Merchant->>Customer: Redirect to provider
        Customer->>Provider: Complete payment (bank login, wallet, QR scan)
        Provider->>Gateway: Callback with result
    else Direct Response
        Provider-->>Gateway: Processing result
    end

    Gateway-->>Merchant: Transaction response
    Gateway->>Merchant: Webhook notification (APPROVED/DECLINED)

Supported Transactions¶

Transaction Type	Supported	Description
PAYMENT	Yes	Collect funds via alternative payment method
REFUND	Depends	Depends on payment provider and method
CAPTURE	No	Not applicable (single-step flow)
VOID	No	Not applicable

Transaction Statuses¶

Status	Description	Final State
CREATED	Transaction created but not yet processed	No
PENDING	Payment submitted and awaiting customer action or provider confirmation	No
APPROVED	Payment successfully completed	Yes
DECLINED	Payment rejected by the provider or bank	Yes
CANCELED	Payment canceled by the customer or system	Yes
INVALID	Transaction marked as invalid due to validation errors	Yes
SESSION_EXPIRED	Payment session expired before completion	Yes

For the full transaction lifecycle, see Supported Transaction Statuses.

Redirect Handling¶

After the customer completes (or abandons) the payment on the provider's page, they are redirected back to the merchant:

Transaction Status	Redirect Destination
APPROVED	Merchant's `return_url`
DECLINED / CANCELED	Merchant's `error_url` or `cancel_url`
PENDING	Awaits callback resolution

Always verify the final transaction status via the Transaction Status API regardless of the redirect outcome.

Important Notes¶

The reference field is idempotent per terminal. Sending the same reference with the same amount and currency returns the existing transaction. Different amount/currency values will result in a validation error.
No card data or encryption is required — the method field specifies the payment type as a simple string.
The browser_info field is not required for payment transactions.
Always subscribe to webhooks to receive the final payment status, as payments are typically processed asynchronously.
The country field may be required by certain providers to determine the correct payment flow or bank selection.
Provider-specific configuration can be passed via the options field.