Direct API Integration¶

Payments – API Integration¶

This page provides guidance for integrating Payments using the Direct API approach. Payments allow you to collect funds from a customer using alternative payment methods such as Open Banking, UPI, wallets, bank transfers, or QR codes.

Your platform is responsible for:

Presenting the available payment methods to the customer
Initiating the payment request with the correct method value
Handling redirects to the payment provider
Handling asynchronous webhook callbacks for final transaction status
Verifying the transaction status via the Transaction Status API

Payment Method¶

When initiating a payment request, specify the payment method in the method field:

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

Request Fields¶

Field	Type	Required	Description
`terminal_id`	string	Yes	Terminal identifier configured for payment transactions
`reference`	string	Yes	Unique payment reference per terminal (1–80 chars)
`method`	enum	Yes	Payment method type. One of `OPEN_BANKING`, `UPI`, `WALLETS`, `BANK_TRANSFER`, `QR_CODE`
`currency`	string	Yes	ISO 4217 currency code (e.g., `EUR`, `THB`, `INR`)
`amount`	integer	Yes	Amount in minor units (e.g., `10000` = 100.00)
`description`	string	Yes	Human-readable description (1–100 chars)
`country`	string	Yes	ISO 3166-1 alpha-2 country code (e.g., `TH`, `IN`)
`customer_ip`	string	Yes	Customer IP address
`return_url`	string	Yes	Redirect URL after a successful payment
`error_url`	string	Yes	Redirect URL after a failed payment
`cancel_url`	string	Yes	Redirect URL after a canceled payment
`customer`	object	No	Customer details
`metadata`	object	No	Arbitrary key-value metadata
`options`	object	No	Provider-specific options

Example Request¶

{
  "terminal_id": "TERM001",
  "reference": "PAY-20260331-001",
  "description": "Order payment via Open Banking",
  "currency": "EUR",
  "amount": 10000,
  "method": "OPEN_BANKING",
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1234567890",
    "address": "123 Example Street",
    "city": "Amsterdam",
    "country": "NL",
    "postal_code": "1012AB"
  },
  "country": "NL",
  "customer_ip": "192.168.1.1",
  "metadata": {
    "order_id": "ORD-12345"
  },
  "return_url": "https://merchant.example.com/return",
  "error_url": "https://merchant.example.com/error",
  "cancel_url": "https://merchant.example.com/cancel"
}

The amount is in minor units. For EUR, 10000 represents 100.00 EUR.

Example Response (Redirect)¶

Most payment methods require the customer to be redirected to the provider's page (e.g., bank login, wallet confirmation):

{
  "result": null,
  "action": null,
  "redirect": {
    "transaction_id": "PyTxAbCdEfGhIjKlMnOp",
    "session_id": "PyTxAbCdEfGhIjKlMnOp",
    "url": "https://provider.example.com/pay?session=abc123"
  },
  "form_submit": null
}

When the response contains a redirect, the merchant must redirect the customer to the provided url. After the customer completes or cancels the payment, they are redirected back to the merchant's return_url.

Example Response (Pending)¶

{
  "result": {
    "id": "PyTxAbCdEfGhIjKlMnOp",
    "merchant_id": "0000000000000fpg-dev",
    "order_id": "ORD_PAY_20260331_001",
    "terminal_id": "TERM001",
    "reference": "PAY-20260331-001",
    "description": "Order payment via Open Banking",
    "currency": "EUR",
    "amount": 10000,
    "customer": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com"
    },
    "processing_result": {
      "payment_provider_id": "PP_OB001",
      "payment_provider_account_id": "PPACCT_EUR001"
    },
    "approved": false,
    "pending": true,
    "channel": "ecommerce",
    "transaction_type": "PAYMENT",
    "status": "PENDING",
    "payment_method": {
      "method": "OPEN_BANKING",
      "type": "payment_open_banking"
    },
    "normalized_amount": 10000,
    "errors": []
  },
  "action": null,
  "redirect": null,
  "form_submit": null
}

Example Response (Approved)¶

{
  "result": {
    "id": "PyTxAbCdEfGhIjKlMnOp",
    "merchant_id": "0000000000000fpg-dev",
    "order_id": "ORD_PAY_20260331_001",
    "terminal_id": "TERM001",
    "reference": "PAY-20260331-001",
    "description": "Order payment via Open Banking",
    "currency": "EUR",
    "amount": 10000,
    "customer": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com"
    },
    "processing_result": {
      "payment_provider_id": "PP_OB001",
      "payment_provider_account_id": "PPACCT_EUR001",
      "approval_code": "AUTH789",
      "reference_number": "REF_PAY_001"
    },
    "approved": true,
    "pending": false,
    "channel": "ecommerce",
    "transaction_type": "PAYMENT",
    "status": "APPROVED",
    "payment_method": {
      "method": "OPEN_BANKING",
      "type": "payment_open_banking"
    },
    "normalized_amount": 10000,
    "errors": []
  },
  "action": null,
  "redirect": null,
  "form_submit": null
}

Processing Codes¶

The processing_code field in the response indicates the result of the transaction:

Code	Name	Description
`0000`	Approved	Transaction approved
`1000`	Declined	Transaction declined
`1001`	Failed	Transaction failed
`1002`	Pending	Transaction pending
`1003`	Canceled	Transaction canceled
`1004`	Insufficient Funds	Declined due to insufficient funds
`1005`	Session Expired	Transaction session expired
`2000`	Invalid Request	General validation error
`2013`	Terminal Not Found	Terminal does not exist
`2014`	Terminal Inactive	Terminal is not active
`2015`	Terminal Not Accepting	Terminal is not accepting payments
`2017`	Merchant Inactive	Merchant is not active

Payment Gateway API - Payment 1.0.0¶

This API processes payment transactions using alternative payment methods such as Open Banking, UPI, wallets, bank transfers, or QR codes.

Access Token: Obtain an access token via OpenID Connect using your client credentials (client_id and client_secret are available in your merchant dashboard). See the Authentication guide for details.

Process Payment Transaction: The /api/transactions/payment endpoint initiates a payment and returns detailed response data.

Important: This endpoint requires an Authorization header with a valid Bearer token.

Servers¶

Description	URL
https://api.example.com	https://api.example.com

Endpoints¶

POST /api/transactions/payment¶

Execute Payment Transaction

Description

Execute a payment transaction using an alternative payment method (Open Banking, UPI, wallets, bank transfer, or QR code).

Requirements: - An Authorization header with a valid Bearer token is required. - The method field must specify one of the supported payment methods. - The terminal must be configured to support payment transactions (TRX_TYPE_PAYMENT).

Key characteristics: - The transaction type is always PAYMENT — no transaction_type field is needed in the request. - No card data or encryption is required. - Payments are typically processed asynchronously with a redirect to the provider. - The initial response may include a redirect URL or a PENDING status. - The final transaction status is delivered via webhook.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`bearerAuth`	header	string	N/A	No	JWT Bearer token

Request body

application/json

{
    "terminal_id": "string",
    "reference": "string",
    "description": "string",
    "currency": "EUR",
    "amount": 21,
    "method": "OPEN_BANKING",
    "customer": {
        "first_name": "string",
        "last_name": "string",
        "address": "string",
        "city": "string",
        "country": "string",
        "postal_code": "string",
        "email": "string",
        "phone": "string",
        "id": "string"
    },
    "metadata": {},
    "return_url": "string",
    "error_url": "string",
    "cancel_url": "string",
    "options": {},
    "customer_ip": "203.0.113.42",
    "country": "NL"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "type": "object",
    "description": "Request to initiate a payment transaction using alternative payment methods.",
    "properties": {
        "terminal_id": {
            "type": "string",
            "description": "Terminal identifier. The terminal must be configured to support payment transactions (`TRX_TYPE_PAYMENT`).",
            "minLength": 5,
            "maxLength": 20
        },
        "reference": {
            "type": "string",
            "description": "Unique payment reference per terminal (max 80 chars). Idempotent — if an order for this reference already exists with the same amount and currency, the existing transaction is returned. Different amount/currency will result in a validation error.\n",
            "minLength": 1,
            "maxLength": 80
        },
        "description": {
            "type": "string",
            "description": "Human-readable payment description.",
            "minLength": 1,
            "maxLength": 100
        },
        "currency": {
            "type": "string",
            "description": "ISO 4217 currency code (e.g., EUR, USD, THB, INR).",
            "example": "EUR",
            "minLength": 3,
            "maxLength": 3
        },
        "amount": {
            "type": "integer",
            "format": "int64",
            "description": "Payment amount in minor units (e.g., 10000 = 100.00 EUR)."
        },
        "method": {
            "type": "string",
            "description": "Payment method type. Determines how the customer will complete the payment.\n",
            "enum": [
                "OPEN_BANKING",
                "UPI",
                "WALLETS",
                "BANK_TRANSFER",
                "QR_CODE"
            ],
            "example": "OPEN_BANKING"
        },
        "customer": {
            "$ref": "#/components/schemas/CustomerDto"
        },
        "metadata": {
            "type": "object",
            "additionalProperties": true,
            "description": "Arbitrary key-value metadata to attach to the payment transaction."
        },
        "return_url": {
            "type": "string",
            "description": "URL to redirect the customer to after a successful payment."
        },
        "error_url": {
            "type": "string",
            "description": "URL to redirect the customer to after a failed payment."
        },
        "cancel_url": {
            "type": "string",
            "description": "URL to redirect the customer to after a canceled payment."
        },
        "options": {
            "type": "object",
            "additionalProperties": true,
            "description": "Provider-specific or payment-type-specific options."
        },
        "customer_ip": {
            "type": "string",
            "description": "Customer's IP address (IPv4 or IPv6). Provide this explicitly when the request reaches the gateway through your own backend, so that provider fraud checks see the end customer's IP rather than your server's.",
            "example": "203.0.113.42"
        },
        "country": {
            "type": "string",
            "description": "ISO 3166-1 alpha-2 country code (e.g., TH, ID, IN, NL).",
            "example": "NL",
            "minLength": 2,
            "maxLength": 2
        }
    },
    "required": [
        "terminal_id",
        "reference",
        "description",
        "currency",
        "amount",
        "method",
        "return_url",
        "error_url",
        "cancel_url",
        "customer_ip",
        "country"
    ]
}

Responses

200 OK422 Unprocessable Content401 Unauthorized

application/json

{
    "result": null,
    "action": null,
    "redirect": {
        "transaction_id": "PyTxAbCdEfGhIjKlMnOp",
        "session_id": "PyTxAbCdEfGhIjKlMnOp",
        "url": "https://provider.example.com/pay?session=abc123"
    },
    "form_submit": null
}

{
    "result": {
        "id": "PyTxAbCdEfGhIjKlMnOp",
        "merchant_id": "0000000000000fpg-dev",
        "order_id": "ORD_PAY_20260331_001",
        "terminal_id": "TERM001",
        "reference": "PAY-20260331-001",
        "description": "Order payment via Open Banking",
        "currency": "EUR",
        "amount": 10000,
        "customer": {
            "first_name": "John",
            "last_name": "Doe",
            "email": "john.doe@example.com"
        },
        "processing_result": {
            "payment_provider_id": "PP_OB001",
            "payment_provider_account_id": "PPACCT_EUR001",
            "approval_code": "AUTH789",
            "reference_number": "REF_PAY_001"
        },
        "approved": true,
        "pending": false,
        "channel": "ecommerce",
        "transaction_type": "PAYMENT",
        "status": "APPROVED",
        "payment_method": {
            "method": "OPEN_BANKING",
            "type": "payment_open_banking"
        },
        "normalized_amount": 10000,
        "processing_code": "0000",
        "errors": []
    },
    "action": null,
    "redirect": null,
    "form_submit": null
}

{
    "result": {
        "id": "PyTxPeNdInGhIjKlMnOp",
        "merchant_id": "0000000000000fpg-dev",
        "order_id": "ORD_PAY_20260331_002",
        "terminal_id": "TERM001",
        "reference": "PAY-20260331-002",
        "description": "UPI payment",
        "currency": "INR",
        "amount": 50000,
        "customer": {
            "first_name": "Jane",
            "last_name": "Smith",
            "email": "jane.smith@example.com"
        },
        "processing_result": {
            "payment_provider_id": "PP_UPI001",
            "payment_provider_account_id": "PPACCT_INR001"
        },
        "approved": false,
        "pending": true,
        "channel": "ecommerce",
        "transaction_type": "PAYMENT",
        "status": "PENDING",
        "payment_method": {
            "method": "UPI",
            "type": "payment_upi"
        },
        "normalized_amount": 50000,
        "processing_code": "1002",
        "errors": []
    },
    "action": null,
    "redirect": null,
    "form_submit": null
}

{
    "result": {
        "id": "PyTxDcLnEdGhIjKlMnOp",
        "merchant_id": "0000000000000fpg-dev",
        "order_id": "ORD_PAY_20260331_003",
        "terminal_id": "TERM001",
        "reference": "PAY-20260331-003",
        "description": "Wallet payment declined",
        "currency": "EUR",
        "amount": 25000,
        "customer": {
            "first_name": "Alex",
            "last_name": "Johnson",
            "email": "alex.johnson@example.com"
        },
        "processing_result": {
            "payment_provider_id": "PP_WAL001",
            "payment_provider_account_id": "PPACCT_EUR002"
        },
        "approved": false,
        "pending": false,
        "channel": "ecommerce",
        "transaction_type": "PAYMENT",
        "status": "DECLINED",
        "payment_method": {
            "method": "WALLETS",
            "type": "payment_wallets"
        },
        "normalized_amount": 25000,
        "processing_code": "1000",
        "errors": []
    },
    "action": null,
    "redirect": null,
    "form_submit": null
}

Schema of the response body

{
    "type": "object",
    "properties": {
        "result": {
            "$ref": "#/components/schemas/ExtendedTransactionDto",
            "description": "Extended transaction details. May be null when a redirect is required."
        },
        "action": {
            "$ref": "#/components/schemas/ActionRequiredDto",
            "description": "Details for any required action."
        },
        "redirect": {
            "$ref": "#/components/schemas/RedirectDto",
            "description": "Redirect information. Present when the customer must be redirected to complete the payment."
        },
        "form_submit": {
            "$ref": "#/components/schemas/FormSubmitDto",
            "description": "Form submission details if required."
        }
    },
    "description": "Response payload for a payment transaction."
}

application/json

{
    "errors": [
        {
            "message": "The size of \"reference\" must be less than or equal to 80. The given size is 100",
            "params": [
                "reference",
                "80",
                "100"
            ],
            "property": "reference"
        }
    ],
    "method": "POST",
    "status": 422
}

Schema of the response body

{
    "type": "object",
    "properties": {
        "errors": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "message": {
                        "type": "string"
                    },
                    "params": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "property": {
                        "type": "string"
                    }
                }
            }
        },
        "method": {
            "type": "string"
        },
        "status": {
            "type": "integer"
        }
    }
}

application/json

{
    "error": "Unauthorized"
}

Schema of the response body

{
    "type": "object",
    "properties": {
        "error": {
            "type": "string"
        }
    }
}

Schemas¶

ActionRequiredDto¶

Name	Type	Description
`payment_data`	string	Encrypted payment data.
`session_id`	string
`token`	string	Base64 encoded data.
`transaction_id`	string
`type`	string	Action type.

CustomerDto¶

Name	Type	Description
`address`	string \| null
`city`	string \| null
`country`	string \| null
`email`	string \| null
`first_name`	string \| null
`id`	string \| null
`last_name`	string \| null
`phone`	string \| null
`postal_code`	string \| null

ExecuteTransactionResponseDto¶

Name	Type	Description
`action`	ActionRequiredDto	Details for any required action.
`form_submit`	FormSubmitDto	Form submission details if required.
`redirect`	RedirectDto	Redirect information. Present when the customer must be redirected to complete the payment.
`result`	ExtendedTransactionDto	Extended transaction details. May be null when a redirect is required.

ExtendedTransactionDto¶

Name	Type	Description
`amount`	integer(int64)
`approved`	boolean
`channel`	string
`currency`	string
`customer`	CustomerDto
`customer_ip`	string \| null
`description`	string
`errors`	Array<>
`id`	string
`merchant_id`	string
`normalized_amount`	integer(int64)
`order_id`	string
`payment_method`	PaymentMethodDataDto
`pending`	boolean
`processing_code`	string	Processing result code. Common values: `0000` (approved), `1000` (declined), `1002` (pending).
`processing_result`	ProcessingResultDto
`redirect_url`	string \| null
`reference`	string
`response_message`	string \| null	Response message from the payment provider.
`status`	TransactionStatus
`terminal_id`	string
`transaction_type`	string	Always `PAYMENT` for this endpoint.

FormSubmitDto¶

Name	Type	Description
`data`
`session_id`	string
`transaction_id`	string
`url`	string

PaymentMethodDataDto¶

Name	Type	Description
`brand`	string \| null
`hash`	string \| null
`masked`	string \| null	Masked payment details if available.
`method`	string	Payment method (e.g., OPEN_BANKING, UPI, WALLETS, BANK_TRANSFER, QR_CODE).
`token`	string \| null
`type`	string	Internal payment method type identifier (e.g., payment_open_banking, payment_upi, payment_wallets).

PaymentRequestDto¶

Name	Type	Description
`amount`	integer(int64)	Payment amount in minor units (e.g., 10000 = 100.00 EUR).
`cancel_url`	string	URL to redirect the customer to after a canceled payment.
`country`	string	ISO 3166-1 alpha-2 country code (e.g., TH, ID, IN, NL).
`currency`	string	ISO 4217 currency code (e.g., EUR, USD, THB, INR).
`customer`	CustomerDto
`customer_ip`	string	Customer's IP address (IPv4 or IPv6). Provide this explicitly when the request reaches the gateway through your own backend, so that provider fraud checks see the end customer's IP rather than your server's.
`description`	string	Human-readable payment description.
`error_url`	string	URL to redirect the customer to after a failed payment.
`metadata`		Arbitrary key-value metadata to attach to the payment transaction.
`method`	string	Payment method type. Determines how the customer will complete the payment.
`options`		Provider-specific or payment-type-specific options.
`reference`	string	Unique payment reference per terminal (max 80 chars). Idempotent — if an order for this reference already exists with the same amount and currency, the existing transaction is returned. Different amount/currency will result in a validation error.
`return_url`	string	URL to redirect the customer to after a successful payment.
`terminal_id`	string	Terminal identifier. The terminal must be configured to support payment transactions (`TRX_TYPE_PAYMENT`).

ProcessingResultDto¶

RedirectDto¶

Name	Type	Description
`session_id`	string
`transaction_id`	string
`url`	string	URL to redirect the customer to complete the payment.

TransactionStatus¶

Type: string

Security schemes¶

Name	Type	Scheme	Description
bearerAuth	http	bearer