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, as an integer (e.g., `10000` = 100.00). Decimal or fractional values such as `100.00` or `"100.00"` are rejected at request validation.
`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 and must be an integer. For EUR, 10000 represents 100.00 EUR. Decimal or fractional values (e.g., 100.00 or "100.00") are rejected at request validation.

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": 85,
    "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, as an integer (e.g., `10000` = 100.00 EUR). Decimal or fractional values such as `100.00` or `\"100.00\"` are rejected at request validation."
        },
        "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"
    ]
}

Response 200 OK

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."
}

Response 422 Unprocessable Entity

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"
        }
    }
}

Response 401 Unauthorized

application/json

{
    "error": "Unauthorized"
}

Schema of the response body

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

Schemas¶

ActionRequiredDto¶

Name	Type
`payment_data`	string
`session_id`	string
`token`	string
`transaction_id`	string
`type`	string

CustomerDto¶

Name	Type
`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
`action`	ActionRequiredDto
`form_submit`	FormSubmitDto
`redirect`	RedirectDto
`result`	ExtendedTransactionDto

ExtendedTransactionDto¶

Name	Type
`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`	ProcessingResultDto
`redirect_url`	string\| null
`reference`	string
`response_message`	string\| null
`status`	TransactionStatus
`terminal_id`	string
`transaction_type`	string

FormSubmitDto¶

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

PaymentMethodDataDto¶

Name	Type
`brand`	string\| null
`hash`	string\| null
`masked`	string\| null
`method`	string
`token`	string\| null
`type`	string

PaymentRequestDto¶

Name	Type
`amount`	integer(int64)
`cancel_url`	string
`country`	string
`currency`	string
`customer`	CustomerDto
`customer_ip`	string
`description`	string
`error_url`	string
`metadata`
`method`	string
`options`
`reference`	string
`return_url`	string
`terminal_id`	string

ProcessingResultDto¶

RedirectDto¶

Name	Type
`session_id`	string
`transaction_id`	string
`url`	string

TransactionStatus¶

Type: string

Security schemes¶

Name	Type	Scheme	Description
bearerAuth	http	bearer