Zoth Payment API

Global

Use these APIs to quote, create, authorize, track, and manage cross-border payment transactions, including cancellation, receipts, status updates, and supporting document uploads. All routes are served under /api/global.

Try requests in Swagger explorer

Flow

Transaction Lifecycle

Transactions follow a simple ordered flow. First create a quote to lock the rate and fee, then create the payment order with sender, receiver, and transaction details.

1. Create Quote

Get rate, fees, tax, and a quote_id valid for 30 minutes.

2. Create Transaction

Submit the payment order using the quote_id.

3. Confirm Transaction

Authorize the payment order. Requires x402 USDT payment based on the stored total_payin_amount.

4. Enquire Transaction

Poll the transaction status until completion.

Connectivity

Host Details

All Global API requests are served from the Zoth Payment host over HTTPS on port 443.

Environment	Base URL	API prefix	Port
Production	https://zpayments.zoth.io	/api/global	443

Example: https://zpayments.zoth.io/api/global/quote

Policy

Access & Privileges

Connections must be made over HTTPS with a minimum of TLS 1.2.
The connecting application must authenticate and obtain access tokens using the provided credentials.
Periodically plan and publish your expected traffic and quota.
Avoid unwanted or repetitive calls that may cause the account to be locked.

Security

Authentication

All requests must be sent over HTTPS and authenticated with a bearer token. Only the headers below are required from your integration.

Field	Type	Length	Required	Description
Authorization	String	-	Mandatory	Bearer {accessToken}
Content-Type	String	-	Mandatory	application/json

Base URL: https://zpayments.zoth.io/api/global

4.1

Create Quote

Create and lock the exchange rate and fee for a payment transaction. The quote_id returned by this API is valid for 30 minutes. The price_guarantee field indicates whether the quote is INDICATIVE or FIRM.

POST/api/global/quote

Required Headers

Field	Type	Length	Required	Description
Authorization	String	-	Mandatory	Bearer {accessToken}
Content-Type	String	-	Mandatory	application/json

Request Fields

Field	Type	Length	Required	Description
sending_country_code	String	2	No	Hardcoded to SG. Clients do not need to send this field.
sending_currency_code	String	3	No	Hardcoded to USD. Clients do not need to send this field.
receiving_country_code	String	2	Yes	Beneficiary receive country; ISO 2 character country code.
receiving_currency_code	String	3	Yes	Beneficiary receive currency; ISO 3 character currency code.
sending_amount	BigDecimal	(15,4)	Conditional	Amount in send currency. When sending_amount is passed, receiving_amount is optional.
receiving_amount	BigDecimal	(15,4)	Yes	Amount in receive currency. If both amounts are sent, sending_amount takes priority.
receiving_mode	String	20	Yes	Delivery mode: BANK, CASHPICKUP, MOBILECASH, or MOBILEWALLET.
type	String	-	Yes	Transaction type. Use SEND.
instrument	String	-	Yes	Instrument type, for example REMITTANCE or BILL PAYMENT.
correspondent	String	-	Conditional	Correspondent name. Mandatory for cash payout and MTO corridors, for example LR, RR, TF.
bank_id	String	60	Conditional	Bank ID. Mandatory for CASHPICKUP when required by corridor rules.
branch_id	String	60	Conditional	Branch ID. Mandatory for CASHPICKUP when required by corridor rules.
service_type	String	3	Yes	C2C, C2B, or B2B. Default: C2C.

Sample Request

JSON

{
  "service_type": "C2C",
  "receiving_country_code": "IN",
  "receiving_currency_code": "INR",
  "receiving_amount": 1000,
  "receiving_mode": "BANK",
  "type": "SEND",
  "instrument": "REMITTANCE"
}

Sample Response

JSON

{
  "status": "success",
  "status_code": 200,
  "data": {
    "quote_id": "1279123122023835",
    "created_at": "2023-08-08T09:23:31.152+04:00",
    "created_at_gmt": "2023-08-08T05:23:31.152Z",
    "expires_at": "2023-08-08T09:53:31.152+04:00",
    "expires_at_gmt": "2023-08-08T05:53:31.152Z",
    "receiving_country_code": "IN",
    "receiving_currency_code": "INR",
    "sending_country_code": "SG",
    "sending_currency_code": "USD",
    "sending_amount": 12,
    "receiving_amount": 1000,
    "total_payin_amount": 19.35,
    "fx_rates": [
      {
        "rate": 83.33333333,
        "base_currency_code": "USD",
        "counter_currency_code": "INR",
        "type": "SELL"
      }
    ],
    "fee_details": [
      {
        "type": "COMMISSION",
        "model": "OUR",
        "currency_code": "USD",
        "amount": 7,
        "description": "Commission"
      },
      {
        "type": "TAX",
        "model": "OUR",
        "currency_code": "USD",
        "amount": 0.35,
        "description": "Tax"
      }
    ],
    "settlement_details": [
      {
        "charge_type": "COMMISSION",
        "value": 2.8,
        "currency_code": "USD"
      },
      {
        "charge_type": "TREASURYMARGIN",
        "value": 0.008,
        "currency_code": "USD"
      }
    ],
    "correspondent_rules": [
      {
        "field": "purpose_of_txn",
        "rule": "it is mandatory"
      },
      {
        "field": "receiver.bank_details.account_number",
        "rule": "it is mandatory"
      }
    ],
    "price_guarantee": "FIRM"
  }
}

Response Fields

Field	Type	Length	Required	Description
status	String	60	Yes	Status description.
status_code	Integer	-	Yes	Status code.
data.quote_id	String	16	Yes	Unique identification key for the quote.
data.created_at / data.created_at_gmt	String	-	Yes	Quote creation timestamp in local time and GMT.
data.expires_at / data.expires_at_gmt	String	-	Yes	Quote expiry timestamp in local time and GMT.
data.sending_country_code / data.sending_currency_code	String	-	Yes	Send country and currency codes.
data.receiving_country_code / data.receiving_currency_code	String	-	Yes	Receive country and currency codes.
data.sending_amount	BigDecimal	-	Yes	Send amount.
data.receiving_amount	BigDecimal	-	Yes	Receive amount.
data.total_payin_amount	BigDecimal	-	Yes	Total amount to be paid in.
data.price_guarantee	String	10	Yes	INDICATIVE or FIRM.
data.fx_rates[]	List	-	Yes	Exchange rate details: rate, base_currency_code, counter_currency_code, type, and optional cost_rate.
data.fee_details[]	List	-	Yes	Fee details: type, model, currency_code, amount, and optional description.
data.settlement_details[]	List	-	Yes	Settlement details: charge_type, value, and currency_code.
data.correspondent_rules[]	List	-	Yes	Validation rules that should be satisfied when creating the transaction.

4.2

Create Transaction

Create a payment order after validating sender, receiver, and transaction details. The request is validated against payload structure, quote validity, corridor mandates, available funds, and screening requirements.

POST/api/global/createtransaction

Required Headers

Field	Type	Length	Required	Description
Authorization	String	-	Mandatory	Bearer {accessToken}
Content-Type	String	-	Mandatory	application/json

Request Fields

Field	Type	Length	Required	Description
type	String	-	Yes	SEND.
source_of_income	String	-	Yes	Sender source of income.
purpose_of_txn	String	-	Yes	Purpose of the transaction.
message	String	200	No	Any free text.
instrument	String	60	Yes	Instrument type: REMITTANCE or BILL PAYMENT.
service_type	String	-	Conditional	C2C, C2B, or B2B. Default: C2C.
sender	Object	-	Yes	Sender details.
sender.agent_customer_number	String	60	No	Agent stored customer ID.
sender.mobile_number	String	20	Yes	Sender mobile number.
sender.email	String	254	No	Sender email address.
sender.first_name	String	60	Yes	Sender first name.
sender.last_name	String	60	Yes	Sender last name.
sender.middle_name	String	60	No	Sender middle name.
sender.date_of_birth	Date	-	Yes	Sender date of birth.
sender.country_of_birth	String	2	No	Sender country of birth.
sender.gender	String	1	No	M or F.
sender.nationality	String	2	Yes	Sender nationality; ISO 2 character country code.
sender.employer	String	300	No	Sender employer name.
sender.profession_code	String	-	No	Sender profession code.
sender.visa_type_code	String	-	No	Sender visa type code.
sender.sender_id[]	List	-	Yes	Sender identification documents.
sender.sender_id[].id_code	String	-	Yes	Sender ID type code. For example, 4 for Emirates ID.
sender.sender_id[].id	String	30	Yes	Sender ID number.
sender.sender_id[].issued_country_code	String	2	Yes	ID issued country code.
sender.sender_id[].issued_on	Date	-	No	ID issue date.
sender.sender_id[].valid_through	Date	-	Yes	ID expiry date.
sender.sender_address[]	List	-	Yes	Sender address details.
sender.sender_address[].address_type	String	-	Yes	PRESENT.
sender.sender_address[].address_line	String	-	Yes	Address line.
sender.sender_address[].post_code	String	-	No	Postal code.
sender.sender_address[].town_name	String	-	Yes	Town name.
sender.sender_address[].country_code	String	2	Yes	Country code.
sender.country_of_incorporation	String	2	Conditional	Country of incorporation; ISO 2 character country code. Required for B2B service_type.
sender.name	String	120	Conditional	Business/company name. Required for B2B service_type.
sender.phone_number	String	20	Conditional	Business phone number. Required for B2B service_type.
sender.type_of_business	String	20	Conditional	Type of business from master data. Required for B2B service_type.
sender.sender_ubos[]	List	-	Conditional	Ultimate Beneficial Owners. Required for B2B service_type.
sender.sender_ubos[].first_name	String	60	Yes	UBO first name.
sender.sender_ubos[].last_name	String	60	Yes	UBO last name.
sender.sender_ubos[].middle_name	String	60	No	UBO middle name.
sender.sender_ubos[].mobile_number	String	20	Yes	UBO mobile number.
sender.sender_ubos[].date_of_birth	Date	-	Yes	UBO date of birth.
sender.sender_ubos[].nationality	String	2	Yes	UBO nationality; ISO 2 character country code.
sender.sender_ubos[].designation_id	String	-	Yes	UBO designation ID.
sender.sender_ubos[].ubo_id[]	List	-	Yes	UBO identification documents.
sender.sender_ubos[].ubo_id[].id_code	String	-	Yes	ID type code.
sender.sender_ubos[].ubo_id[].id	String	30	Yes	ID number.
sender.sender_ubos[].ubo_id[].issued_on	Date	-	No	ID issue date.
sender.sender_ubos[].ubo_id[].valid_through	Date	-	Yes	ID expiry date.
receiver	Object	-	Yes	Receiver or beneficiary details.
receiver.mobile_number	String	20	Yes	Receiver mobile number.
receiver.first_name / receiver.last_name	String	60	Conditional	Receiver individual name fields.
receiver.name	String	120	Conditional	Receiver business/entity name. Mandatory for C2B and B2B.
receiver.nationality / receiver.relation_code	String	-	Conditional	Receiver nationality and relationship code with sender.
receiver.bank_details	Object	-	Conditional	Required for BANK receiving mode. Includes account_type_code, account_number or IBAN, iso_code, routing_code, sort_code, and optional bank/correspondent identifiers.
receiver.cashPickup_details	Object	-	Conditional	Required for CASHPICKUP receiving mode. Includes correspondent, correspondent_id, and correspondent_location_id.
receiver.mobileWallet_details	Object	-	Conditional	Required for MOBILEWALLET receiving mode. Includes correspondent, bank_id, branch_id, and wallet_id.
receiver.receiver_id[]	List	-	Conditional	Receiver identification documents. Required for B2B service_type.
receiver.receiver_address[]	List	-	Conditional	Receiver address details including address_type, address_line, town_name, country_subdivision, and country_code.
transaction	Object	-	Yes	Transaction details.
transaction.quote_id	String	-	Yes	Quote ID returned by Create Quote.
transaction.agent_transaction_ref_number	String	-	Conditional	Your unique transaction reference.
transaction.receiving_mode	String	20	No	Delivery mode: BANK, CASHPICKUP, or MOBILEWALLET.
transaction.sending_country_code	String	2	Yes	Sending country; ISO 2 character country code.
transaction.sending_currency_code	String	3	No	Sending currency; ISO 3 character currency code.
transaction.receiving_country_code / receiving_currency_code	String	-	Conditional	Receiving country and currency codes.
transaction.sending_amount / receiving_amount	BigDecimal	-	Conditional	Transaction amount. If both are passed, sending_amount takes priority.
transaction.payment_mode	String	2	Conditional	Mandatory when payment is collected by zoth.
transaction.channel_quote_id	String	36	No	Channel quote ID.
transaction.ordering_institution	Object	-	Conditional	Ordering institution details, including name and institution_address.
transaction.proofs[]	List	-	Conditional	Supporting documents. Required for B2B service_type. Includes content_type, document_type, and documents.base64_front_data.

Sample Request - Bank Transfer

JSON

{
  "type": "SEND",
  "source_of_income": "SLRY",
  "purpose_of_txn": "SAVG",
  "instrument": "REMITTANCE",
  "message": "Agency transaction",
  "sender": {
    "agent_customer_number": "123456785fg41vdd",
    "mobile_number": "+971503248026",
    "email": "test@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "sender_id": [
      {
        "id_code": "4",
        "id": "784199554586091",
        "issued_on": "2023-12-10",
        "valid_through": "2026-11-05"
      }
    ],
    "date_of_birth": "1990-08-22",
    "country_of_birth": "IN",
    "sender_address": [
      {
        "address_type": "PRESENT",
        "address_line": "123 Main St",
        "post_code": "9054",
        "town_name": "Dubai",
        "country_code": "AE"
      }
    ],
    "nationality": "IN"
  },
  "receiver": {
    "mobile_number": "+919586741508",
    "first_name": "Jane",
    "last_name": "Smith",
    "date_of_birth": "1990-08-22",
    "gender": "F",
    "receiver_address": [
      {
        "address_type": "PRESENT",
        "address_line": "456 Park Ave",
        "town_name": "Karachi",
        "country_code": "PK"
      }
    ],
    "nationality": "PK",
    "relation_code": "32",
    "bank_details": {
      "account_type_code": "1",
      "account_number": "67095294579",
      "iso_code": "ALFHPKKA068"
    }
  },
  "transaction": {
    "quote_id": "{{quote_id}}",
    "sending_country_code": "AE",
    "ordering_institution": {
      "name": "abc",
      "institution_address": {
        "country_code": "SG",
        "address_line": "ZAYED TOWER",
        "address_type": "PRESENT",
        "town_name": "HAWALLI",
        "post_code": "123456"
      }
    }
  }
}

Sample Request - Cash Pickup

JSON

{
  "type": "SEND",
  "source_of_income": "SLRY",
  "purpose_of_txn": "SAVG",
  "instrument": "REMITTANCE",
  "message": "Cash pickup transaction",
  "sender": {
    "agent_customer_number": "123456785fg41vdd",
    "mobile_number": "+971523236963",
    "first_name": "MANU",
    "last_name": "GARCIA",
    "date_of_birth": "1973-07-12",
    "gender": "M",
    "nationality": "PH",
    "profession_code": "550",
    "employer": "zoth",
    "sender_id": [
      {
        "id_code": "4",
        "id": "784199554586091",
        "issued_on": "2023-12-10",
        "valid_through": "2026-11-05"
      }
    ],
    "sender_address": [
      {
        "address_type": "PRESENT",
        "address_line": "123 Main St",
        "town_name": "Dubai",
        "country_code": "AE"
      }
    ]
  },
  "receiver": {
    "mobile_number": "+919586741508",
    "first_name": "Jane",
    "last_name": "Smith",
    "date_of_birth": "1990-08-22",
    "gender": "F",
    "nationality": "PK",
    "relation_code": "32",
    "cashPickup_details": {
      "correspondent": "RR",
      "correspondent_id": "INOPCP",
      "correspondent_location_id": "OP"
    },
    "receiver_address": [
      {
        "address_type": "PRESENT",
        "address_line": "456 Park Ave",
        "town_name": "Karachi",
        "country_code": "PK"
      }
    ]
  },
  "transaction": {
    "quote_id": "{{quote_id}}",
    "receiving_mode": "CASHPICKUP",
    "sending_country_code": "AE"
  }
}

Sample Request - Mobile Wallet

JSON

{
  "type": "SEND",
  "source_of_income": "SLRY",
  "purpose_of_txn": "SAVG",
  "instrument": "REMITTANCE",
  "message": "Mobile wallet transaction",
  "sender": {
    "agent_customer_number": "1238121217803583",
    "mobile_number": "+96565919591",
    "first_name": "DIGITNINE",
    "middle_name": "KUWAIT",
    "last_name": "ALBERT",
    "date_of_birth": "1975-10-21",
    "country_of_birth": "IN",
    "nationality": "IN",
    "sender_id": [
      {
        "id_code": "11",
        "id": "296070902001",
        "issued_on": "2016-02-07",
        "valid_through": "2025-09-23"
      }
    ],
    "sender_address": [
      {
        "address_type": "PRESENT",
        "address_line": "ZAYED TOWER",
        "town_name": "HAWALLI",
        "post_code": "123456",
        "country_code": "KW"
      }
    ]
  },
  "receiver": {
    "mobile_number": "1234567890",
    "first_name": "TEST",
    "last_name": "TEST",
    "nationality": "IN",
    "relation_code": "4",
    "mobileWallet_details": {
      "correspondent": "LR",
      "bank_id": "{{bank_id}}",
      "branch_id": "{{branch_id}}",
      "wallet_id": "{{wallet_id}}"
    },
    "receiver_address": [
      {
        "address_type": "PRESENT",
        "address_line": "addressssss",
        "town_name": "abc",
        "country_code": "IN"
      }
    ]
  },
  "transaction": {
    "quote_id": "{{quote_id}}",
    "receiving_mode": "MOBILEWALLET",
    "sending_country_code": "KW"
  }
}

Sample Request - B2B

JSON

{
  "type": "SEND",
  "source_of_income": "SLRY",
  "purpose_of_txn": "SAVG",
  "instrument": "REMITTANCE",
  "message": "Agency transaction",
  "service_type": "B2B",
  "sender": {
    "agent_customer_number": "123812967893581",
    "country_of_incorporation": "IN",
    "name": "Zoth",
    "type_of_business": "1",
    "phone_number": "1234567892",
    "sender_address": [
      {
        "country_code": "SG",
        "country_subdivision": "SG",
        "address_line": "ZAYED TOWER",
        "town_name": "HAWALLI",
        "post_code": "33333",
        "pobox": "555555"
      }
    ],
    "sender_id": [
      {
        "valid_through": "2028-12-12",
        "issued_on": "2016-02-07",
        "id": "3459485113",
        "id_code": "3",
        "issued_country_code": "SG"
      }
    ],
    "sender_ubos": [
      {
        "last_name": "kuamr",
        "mobile_number": "+7037233471",
        "middle_name": "",
        "date_of_birth": "1976-10-21",
        "first_name": "ajay",
        "designation_id": "5",
        "nationality": "IN",
        "ubo_id": [
          {
            "valid_through": "2031-12-09",
            "issued_on": "2011-12-03",
            "id": "X82377455501",
            "id_code": "2"
          }
        ]
      }
    ]
  },
  "receiver": {
    "name": "pdd financial holdings enterprise pvt.ltd",
    "relation_code": "1",
    "mobile_number": "+78676565462",
    "nationality": "US",
    "receiver_address": [
      {
        "address_type": "PRESENT",
        "address_line": "TCR",
        "town_name": "THRISSUR",
        "country_code": "US"
      }
    ],
    "receiver_id": [
      {
        "id_code": "2",
        "id": "784199554586091",
        "issued_on": "2023-12-10",
        "valid_through": "2029-12-10"
      }
    ],
    "bank_details": {
      "account_type_code": "1",
      "iso_code": "EWBAKUS66XX",
      "account_number": "9934572443993487"
    }
  },
  "transaction": {
    "quote_id": "{{quote_id}}",
    "sending_country_code": "SG",
    "agent_transaction_ref_number": "{{quote_id}}",
    "proofs": [
      {
        "content_type": "image/png",
        "document_type": "IDISSUER",
        "documents": {
          "base64_front_data": "<<base64_encoded_data>>"
        }
      }
    ]
  }
}

Sample Response

JSON

{
  "status": "success",
  "status_code": 200,
  "data": {
    "state": "ACCEPTED",
    "sub_state": "ORDER_ACCEPTED",
    "transaction_ref_number": "7028126115519815",
    "transaction_date": "2026-06-04T12:57:32.215Z",
    "transaction_gmt_date": "2026-06-04T12:57:32.215Z",
    "expires_at": "2026-06-04T13:27:32.215Z",
    "expires_at_gmt": "2026-06-04T13:27:32.215Z",
    "agent_transaction_ref_number": "TPSG347345678979584",
    "agent_ref_number": "7028126115519815",
    "delivery_ref_number": "7028126115519815",
    "receiving_country_code": "BD",
    "receiving_currency_code": "BDT",
    "sending_country_code": "SG",
    "sending_currency_code": "USD",
    "sending_amount": 163.0,
    "receiving_amount": 20000.0,
    "total_payin_amount": 163.0,
    "correspondent_id": "79795",
    "correspondent_location_id": "68145131",
    "account_category": "UNDEFINED",
    "transfer_mode": "NEFT",
    "fx_rates": [
      {
        "rate": 122.7,
        "type": "SELL",
        "base_currency_code": "USD",
        "counter_currency_code": "BDT"
      },
      {
        "rate": 0.00814996,
        "type": "SELL",
        "base_currency_code": "BDT",
        "counter_currency_code": "USD"
      }
    ],
    "fee_details": [
      {
        "type": "COMMISSION",
        "model": "OUR",
        "amount": 0,
        "description": "Commission",
        "currency_code": "USD"
      },
      {
        "type": "TAX",
        "model": "OUR",
        "amount": 0,
        "description": "Tax",
        "currency_code": "USD"
      }
    ],
    "settlement_details": [
      {
        "value": 0,
        "charge_type": "COMMISSION",
        "currency_code": "USD"
      },
      {
        "value": 0,
        "charge_type": "INPUTTAX",
        "currency_code": "USD"
      },
      {
        "value": 0,
        "charge_type": "TREASURYMARGIN",
        "currency_code": "USD"
      }
    ],
    "price_guarantee": "FIRM"
  }
}

Response Fields

Field	Type	Length	Required	Description
status	String	60	Yes	Status description.
status_code	Integer	-	Yes	Status code.
data.state / data.sub_state	String	-	Yes	Transaction state and sub-state, for example ACCEPTED / ORDER_ACCEPTED.
data.transaction_ref_number	String	16	Yes	Unique transaction reference number.
data.transaction_date / data.transaction_gmt_date	String	-	Yes	Transaction date and time in local time and GMT.
data.expires_at / data.expires_at_gmt	String	-	Yes	Payment expiry date and time in local time and GMT.
data.agent_transaction_ref_number	String	60	Yes	Agent transaction reference number.
data.agent_ref_number / data.delivery_ref_number	String	-	Yes	Agent and delivery reference numbers. Delivery reference becomes UTR once received from the processing bank.
data.sending_* / data.receiving_*	String \| BigDecimal	-	Yes	Country, currency, and amount details for both send and receive legs.
data.total_payin_amount	BigDecimal	-	Yes	Total payin amount.
data.correspondent_id / data.correspondent_location_id	String	-	Yes	Correspondent identifiers used for processing.
data.account_category	String	-	No	Account category.
data.transfer_mode	String	-	Yes	Transfer mode, for example NEFT.
data.fx_rates[]	List	-	Yes	Exchange rate details.
data.fee_details[]	List	-	Yes	Fee details.
data.settlement_details[]	List	-	Yes	Settlement details.
data.price_guarantee	String	10	Yes	INDICATIVE or FIRM.

4.3

Confirm Transaction

Authorize the payment order from the sending institute to the processing institute. This endpoint is protected by x402 payment: the first request returns HTTP 402 with payment requirements, and a retry with a valid X-Payment header settles USDT on Base. The payment amount is derived from total_payin_amount stored when the transaction was created.

POST/api/global/confirmtransaction

x402 payment

Confirm Transaction uses x402, an open HTTP payment standard that lets services charge for API access directly over HTTP using the 402 Payment Required status code—no separate billing accounts or checkout flows.

How it works for this endpoint:

Send POST with your Bearer token and transaction_ref_number.
If payment has not been made yet, the server responds with HTTP 402 and payment instructions in the response body. The required amount is USDT on Base mainnet, derived from total_payin_amount stored when the transaction was created.
Your client prepares a signed payment payload (Permit2 USDT authorization) and retries the same request with an X-Payment header.
The server verifies and settles the payment, confirms the transaction with the upstream provider, and returns HTTP 200 with the confirmation state.

Required Headers

Field	Type	Length	Required	Description
Authorization	String	-	Mandatory	Bearer {accessToken}
Content-Type	String	-	Mandatory	application/json

Request Fields

Field	Type	Length	Required	Description
transaction_ref_number	String	16	Yes	Transaction reference number from the Create Transaction API.

Sample Request

JSON

{
  "transaction_ref_number": "1276122106256978"
}

Sample Response

JSON

{
  "status": "success",
  "status_code": 200,
  "data": {
    "state": "IN_PROGRESS",
    "sub_state": "PAYMENT_SETTLED",
    "transaction_ref_number": "1276122106256978"
  }
}

Response Fields

Field	Type	Length	Required	Description
state	String	60	Yes	Transaction state.
sub_state	String	120	Yes	Transaction sub-state.
transaction_ref_number	String	16	Yes	Transaction reference number.

4.4

Enquire Transaction

Return the current status of a transaction. Use this API to poll for transaction progress at periodic intervals. The state and sub_state fields describe the current processing stage.

GET/api/global/enquire-transaction?transaction_ref_number=<<ref>>

Required Headers

Field	Type	Length	Required	Description
Authorization	String	-	Mandatory	Bearer {accessToken}
Content-Type	String	-	Mandatory	application/json

Query Parameters

Field	Type	Length	Required	Description
transaction_ref_number	String	16	Mandatory	Transaction reference number that uniquely identifies the transaction.

Sample Response

JSON

{
  "status": "success",
  "status_code": 200,
  "data": {
    "state": "IN_PROGRESS",
    "sub_state": "AML_PENDING",
    "transaction_gmt_date": "2022-03-23T09:18:42.73Z",
    "transaction_date": "2022-03-23T13:18:42.73+04:00",
    "type": "SEND",
    "instrument": "REMITTANCE",
    "source_of_income": "SLRY",
    "purpose_of_txn": "SAVG",
    "message": "Agency transaction",
    "sender": {
      "mobile_number": "+971523236963",
      "first_name": "JOHN",
      "last_name": "DOE",
      "nationality": "PH"
    },
    "receiver": {
      "mobile_number": "+919586741508",
      "first_name": "Jane",
      "last_name": "Smith"
    },
    "transaction": {
      "quote_id": "1279122310938710",
      "receiving_amount": 7576.39,
      "receiving_currency_code": "PKR",
      "receiving_mode": "BANK",
      "sending_amount": 100,
      "sending_currency_code": "AED"
    }
  }
}

4.5

Cancel Transaction

Cancel a transaction after validating the transaction number and status. Cancellation is subject to the transaction's current state.

POST/api/global/canceltransaction

Required Headers

Field	Type	Length	Required	Description
Authorization	String	-	Mandatory	Bearer {accessToken}
Content-Type	String	-	Mandatory	application/json

Request Fields

Field	Type	Length	Required	Description
transaction_ref_number	String	16	Yes	Transaction reference number that uniquely identifies the transaction.
cancel_reason	String	60	Yes	Cancellation reason code. Fetch the valid ENUM values from the Get Codes API using key cancel_reason_codes_list.
remarks	String	40	Yes	Additional message or remarks.

Sample Request

JSON

{
  "transaction_ref_number": "1276122106615570",
  "cancel_reason": "R6",
  "remarks": "Account of the payment is incorrect"
}

Sample Response

JSON

{
  "status": "success",
  "status_code": 200,
  "data": {
    "state": "IN_PROGRESS",
    "sub_state": "CANCELLATION_REQUEST_CREATED",
    "transaction_ref_number": "1276122106615570"
  }
}

Response Fields

Field	Type	Length	Required	Description
state	String	60	Yes	Transaction state.
sub_state	String	120	Yes	Transaction sub-state.
transaction_ref_number	String	16	Yes	Transaction reference number.

Cancellation reason codes: Fetch the full list dynamically from the Get Codes API at /api/global/codes?code=CANCEL_REASON_CODES. The response returns a cancel_reason_codes array of objects with code and name fields (for example, code: "R7", name: "Incorrect Recipient").

Cancellation / Rejection Error Codes

Error Code	HTTP Status	Message	Scenario	Retry / Reject
40004	404	Partner not found	Partner configuration not found for the agent	Retry
40004	404	Transaction not found	Invalid or non-existent transaction reference number	Retry
40100	406	The transaction is not confirmed yet	When payment is not settled yet	Retry
40100	406	Cannot Cancel transaction when AML Pending	When AML is pending	Retry
40100	406	Cancel Reason is invalid	Invalid cancel reason code passed	Reject
40110	406	Transaction already in the cancellation processing state	Cancellation already in progress	Reject
40110	406	The transaction is already processed	Transaction is Credited, Reconciled, or Cancellation completed	Reject
8076401	406	Cancellation is not acceptable since already processed	Transaction already processed by correspondent	Reject
8076402	406	Cancellation is not acceptable since already in progress	Cancellation request already submitted to correspondent	Reject
8076403	406	Transaction is not acceptable since payment not yet settled	Payment not yet settled with correspondent	Retry
8076404	406	Cancel reason is not acceptable	Correspondent rejected the cancel reason code	Reject
8076405	406	Cancellation is not acceptable	Correspondent declined the cancellation request	Reject
8076406	406	Cancellation is not acceptable since already cancelled	Transaction has already been cancelled	Reject

Rejection / Cancellation Remark Codes

These remark codes are returned in the Enquire Transaction response under the remarks field when a transaction is rejected or cancelled.

Remark Code	Remark
ERR001	Account Not Valid
ERR002	Rejected - AML Compliance
ERR003	Regulatory/Compliance Violation
ERR004	Customer Profile Expired
ERR005	Sender Limit Exceeded
ERR006	Beneficiary Limit Exceeded
ERR007	Cancelled as per Customer Request
ERR008	Partner Bank - IBFT Failure
ERR009	Name Mismatch - Account Holder vs. Beneficiary
ERR010	System/Technical Error
ERR011	Transaction Timeout
ERR012	Invalid Banking Details - IFSC/Branch/SWIFT Code Error
ERR013	OR Remarks Test
ERR014	Invalid account details/name/phone
ERR015	Regulatory/Compliance Violation
ERR016	Customer Profile Expired
ERR017	Cancelled as per Customer Request
ERR018	Partner Bank - IBFT Failure
ERR019	System/Technical Error
ERR020	Invalid Banking Details/IFSC/Branch/SWIFT Code Error
ERR021	Name Mismatch - Account Holder vs. Beneficiary
ERR022	Mobile Wallet account invalid
ERR023	Quote Expired
ERR024	Sender Limit Deficit/Exceeded
ERR025	Beneficiary Limit Deficit/Exceeded
ERR026	Rejected as per partner bank
ERR027	Validation Failed
ERR028	Invalid payment Type
ERR029	Blocked / Restricted Country
ERR030	Max retry limit reached
ERR031	Wrong service selected
ERR032	Partner side Transaction Timeout

4.6

Transaction Receipt

Return the invoice report of the transaction as base64-encoded data.

GET/api/global/transaction-receipt?transaction_ref_number=<<ref>>

Required Headers

Field	Type	Length	Required	Description
Authorization	String	-	Mandatory	Bearer {accessToken}
Content-Type	String	-	Mandatory	application/json

Query Parameters

Field	Type	Length	Required	Description
transaction_ref_number	String	16	Mandatory	Transaction reference number that uniquely identifies the transaction.

Sample Response

JSON

{
  "status": "success",
  "status_code": 200,
  "data": {
    "data": "JVBERi0xLjQKMSAwIG9iago8PAovVGl0bGUg..."
  }
}

Response Fields

Field	Type	Length	Required	Description
status	String	60	Yes	Status description.
status_code	Integer	-	Yes	Status code.
data.data	String	-	Yes	Base64-encoded transaction receipt / invoice report.

4.7

Transaction Status Update

Update the status of a transaction whose fulfillment happens in the partner network. Allowed status values are TRANSMITTED, CREDITED, AVAILABLE_PAID, and CANCELLATION_COMPLETED.

PUT/api/global/status-update

Required Headers

Field	Type	Length	Required	Description
Authorization	String	-	Mandatory	Bearer {accessToken}
Content-Type	String	-	Mandatory	application/json

Request Fields

Field	Type	Length	Required	Description
transaction_ref_number	String	16	Yes	Transaction reference number that uniquely identifies the transaction.
status	String	60	Yes	Transaction status to set. Allowed values: TRANSMITTED, CREDITED, AVAILABLE_PAID, CANCELLATION_COMPLETED.

Sample Request

JSON

{
  "transaction_ref_number": "1276122106256978",
  "status": "CREDITED"
}

Sample Response

JSON

{
  "status": "success",
  "status_code": 200,
  "data": {
    "status": "ACKNOWLEDGED"
  }
}

Response Fields

Field	Type	Length	Required	Description
status	String	-	Yes	Status description.
status_code	Integer	-	Yes	Status code.
data.status	String	-	Yes	Acknowledgement value. Always returns ACKNOWLEDGED on success.

4.8

Documents Upload

Upload supporting documents (for example source of funds proof or ID documents) for a transaction. Documents are sent as base64-encoded data.

POST/api/global/transaction-documents

Required Headers

Field	Type	Length	Required	Description
Authorization	String	-	Mandatory	Bearer {accessToken}
Content-Type	String	-	Mandatory	application/json

Request Fields

Field	Type	Length	Required	Description
transaction_ref_number	String	16	Yes	Transaction reference number that uniquely identifies the transaction.
proof[]	List	-	Yes	Array of document proof objects.
proof[].content_type	String	-	Yes	MIME type of the document, for example image/png, image/jpeg, application/pdf.
proof[].document_type	String	-	Yes	Type of document, for example SOURCE or IDISSUER.
proof[].documents.base64_front_data	String	-	Yes	Base64-encoded front side of the document.
proof[].documents.base64_back_data	String	-	No	Base64-encoded back side of the document.

Sample Request

JSON

{
  "transaction_ref_number": "1279124119281448",
  "proof": [
    {
      "content_type": "image/png",
      "document_type": "SOURCE",
      "documents": {
        "base64_front_data": "<<base64_encoded_data>>",
        "base64_back_data": "<<base64_encoded_data>>"
      }
    }
  ]
}

Sample Response

JSON

{
  "status": "success",
  "status_code": 200,
  "data": {
    "message": "Documents uploaded successfully"
  }
}

Master Data

Get Codes

Return master data for ID types, relationships, professions, purposes, payment modes, instruments, receiving modes, fee types, address types, income range types, correspondents, cancellation reasons, and account types. Returns all types if no code is supplied.

GET/api/global/codes

Example: /api/global/codes?code=PURPOSE_OF_TRANSACTIONS&service_type=C2C

Required Headers

Field	Type	Length	Required	Description
Authorization	String	-	Mandatory	Bearer {accessToken}
Content-Type	String	-	Mandatory	application/json

Query Parameters

Field	Type	Length	Required	Description
code	String	-	No	Master data code key to filter the response, for example PURPOSE_OF_TRANSACTIONS. Returns all types if omitted.
service_type	String	-	No	Service type filter: C2C, C2B, or B2B.

Sample Response

JSON

{
  "status": "success",
  "status_code": 200,
  "data": {
    "purposes_of_transactions": [
      { "code": "FAMA", "name": "Family Maintenance" },
      { "code": "MDCS", "name": "Medical expenses" },
      { "code": "LOAR", "name": "REPAYMENT OF LOAN" },
      { "code": "SAVG", "name": "Savings" }
    ]
  }
}

Master Data

Get Service Corridor

Fetch service details, corridor details, currency details, and agent details for a given receiving mode and country. Use this to validate which corridors and currencies are supported before quoting.

GET/api/global/service-corridor

Example: /api/global/service-corridor?receiving_mode=BANK&receiving_country_code=PH

Required Headers

Field	Type	Length	Required	Description
Authorization	String	-	Mandatory	Bearer {accessToken}
Content-Type	String	-	Mandatory	application/json

Query Parameters

Field	Type	Length	Required	Description
receiving_mode	String	-	No	Delivery mode filter: BANK, CASHPICKUP, MOBILEWALLET.
receiving_country_code	String	2	No	Receiving country; ISO 2 character country code.

Sample Response

JSON

{
  "status": "success",
  "status_code": 200,
  "data": [
    {
      "instrument": "REMITTANCE",
      "transaction_type": "SEND",
      "receiving_mode": "BANK",
      "sending_country": "UNITED ARAB EMIRATES",
      "sending_country_code": "AE",
      "receiving_country": "Philippines",
      "receiving_country_code": "PH",
      "limit_currency": "Philippine Peso",
      "limit_currency_code": "PHP",
      "limit_min_amount": 1,
      "limit_per_transaction": 4600000,
      "send_min_amount": 50,
      "send_max_amount": 300000,
      "corridor_currencies": [
        {
          "correspondent": "LR",
          "anywhere": 0,
          "sending_currency": "UAE Dirham",
          "sending_currency_code": "AED",
          "receiving_currency": "Philippine Peso",
          "receiving_currency_code": "PHP",
          "correspondent_name": "ZothRemittance"
        }
      ]
    }
  ]
}

Master Data

Get Rates

Return indicative exchange rates between sending and receiving countries and currencies.

GET/api/global/rates

Example:

/api/global/rates?sending_country_code=AE&sending_currency_code=AED&receiving_country_code=IN&receiving_currency_code=INR

Required Headers

Field	Type	Length	Required	Description
Authorization	String	-	Mandatory	Bearer {accessToken}
Content-Type	String	-	Mandatory	application/json

Query Parameters

Field	Type	Length	Required	Description
sending_country_code	String	2	Yes	Sending country; ISO 2 character country code.
sending_currency_code	String	3	Yes	Sending currency; ISO 3 character currency code.
receiving_country_code	String	2	Yes	Receiving country; ISO 2 character country code.
receiving_currency_code	String	3	Yes	Receiving currency; ISO 3 character currency code.

Sample Response

JSON

{
  "status": "success",
  "status_code": 200,
  "data": [
    {
      "rate": 22.75,
      "base_currency_code": "AED",
      "counter_currency_code": "INR",
      "type": "SELL"
    }
  ]
}

Master Data

Get Banks

Return banks available in the receiving country, optionally filtered by receiving mode, correspondent, or bank id. Use this before creating mobile-wallet or cash-pickup transactions that require bank_id.

GET/api/global/banks

Example: /api/global/banks?receiving_country_code=IN&receiving_mode=MOBILEWALLET&correspondent=LR

Required Headers

Field	Type	Length	Required	Description
Authorization	String	-	Mandatory	Bearer {accessToken}
Content-Type	String	-	Mandatory	application/json

Query Parameters

Field	Type	Length	Required	Description
receiving_country_code	String	2	Mandatory	Receiving country; ISO 2 or 3 character country code.
receiving_mode	String	-	No	Delivery mode filter: BANK, CASHPICKUP, MOBILEWALLET.
correspondent	String	-	No	Correspondent filter, for example LR or RR.
bank_id	String	-	No	Optional bank id filter.

Sample Response

JSON

{
  "status": "success",
  "status_code": 200,
  "data": [
    {
      "bank_id": "CBIN",
      "bank_name": "Central Bank of India",
      "iso_code": "CBININBB068",
      "routing_code": "068",
      "country_code": "IN"
    }
  ]
}

Master Data

Get Branches

Return branches for a bank in the receiving country, optionally filtered by receiving mode, correspondent, or branch id. Use branch_id from this response when creating mobile-wallet transactions.

GET/api/global/banks/{bank_id}/branches

Example: /api/global/banks/CBIN/branches?receiving_country_code=IN&receiving_mode=MOBILEWALLET

Required Headers

Field	Type	Length	Required	Description
Authorization	String	-	Mandatory	Bearer {accessToken}
Content-Type	String	-	Mandatory	application/json

Query Parameters

Field	Type	Length	Required	Description
receiving_country_code	String	2	Mandatory	Receiving country; ISO 2 or 3 character country code.
receiving_mode	String	-	No	Delivery mode filter: BANK, CASHPICKUP, MOBILEWALLET.
correspondent	String	-	No	Correspondent filter, for example LR or RR.
branch_id	String	-	No	Optional branch id filter.

Sample Response

JSON

{
  "status": "success",
  "status_code": 200,
  "data": [
    {
      "branch_id": "068",
      "branch_name": "Mylapore",
      "bank_id": "CBIN",
      "bank_name": "Central Bank of India",
      "iso_code": "CBININBB068",
      "ifsc_code": "CBIN0000068"
    }
  ]
}