Global Payments

Global payments gateway

Coverage across Latin America, Asia and Africa. You integrate a single API. Baanko routes automatically by country, currency and payment method.

Supported Countries and Methods

Latin America

Country	Currency	Code	Pay-in Method	Payout Method
Brazil	Real	`BRL`	PIX	PIX (CPF/CNPJ/Email/Phone/EVP)
Mexico	Mexican peso	`MXN`	Local transfer	SPEI (CLABE)
Peru	Peruvian sol	`PEN`	Local transfer	Bank transfer
Chile	Chilean peso	`CLP`	Local transfer	Bank transfer
Colombia	Colombian peso	`COP`	PSE / Transfer	Bank account
Venezuela	Bolivar	`VES`	Local transfer	Bank transfer
Ecuador	Dollar (local)	`USD`	Local transfer	Bank transfer
Argentina	Argentine peso	`ARS`	Local transfer	Bank transfer

Asia

Country	Currency	Code	Pay-in Method	Payout Method
India	Rupee	`INR`	UPI / IMPS	UPI (VPA) / IMPS / NEFT (IFSC)
Indonesia	Rupiah	`IDR`	Virtual Account	Bank transfer
Russia	Ruble	`RUB`	Local transfer	Bank transfer
Philippines	Peso	`PHP`	Local transfer	Card / GCash
Malaysia	Ringgit	`MYR`	FPX / Online banking	Bank transfer
Pakistan	Rupee	`PKR`	EasyPaisa / JazzCash	EasyPaisa / JazzCash
Bangladesh	Taka	`BDT`	bKash / Nagad	bKash / Nagad

Africa

Country	Currency	Code	Pay-in Method	Payout Method
Kenya	Shilling	`KES`	M-Pesa	M-Pesa
Nigeria	Naira	`NGN`	Bank transfer	Bank account (CBN)
Tanzania	Shilling	`TZS`	Tigo Pesa / Airtel	Mobile Money

Authentication

All endpoints accept API Key authentication (recommended for server-to-server).

Header	Description
`X-Client-Id`	Your account's client ID
`X-API-Key`	Secret API key

Both headers must be sent together. Sending only one results in a 403 Forbidden error.

Create Charge (Pay-in)

POSThttps://baanko.app/api/transaction/create

Example - Brazil (BRL / PIX)

bash

curl --location 'https://baanko.app/api/transaction/create' \
  --header 'Content-Type: application/json' \
  --header 'X-Client-Id: cli_abc123' \
  --header 'X-API-Key: sk_live_xxxx' \
  --header 'Idempotency-Key: order-BR-00451' \
  --data '{
    "amount": 25000,
    "paymentMethod": "PIX",
    "currency": "BRL",
    "postbackUrl": "https://yoursite.com/webhook",
    "customer": {
      "name": "Maria Souza",
      "email": "maria@email.com",
      "externalRef": "usr_789",
      "document": { "number": "98765432100", "type": "CPF" }
    },
    "items": [{ "title": "Balance top-up", "unitPrice": 25000, "quantity": 1 }]
  }'

Example - Mexico (MXN)

bash

curl --location 'https://baanko.app/api/transaction/create' \
  --header 'Content-Type: application/json' \
  --header 'X-Client-Id: cli_abc123' \
  --header 'X-API-Key: sk_live_xxxx' \
  --header 'Idempotency-Key: order-MX-00452' \
  --data '{
    "amount": 50000,
    "paymentMethod": "TRANSFER",
    "currency": "MXN",
    "postbackUrl": "https://yoursite.com/webhook",
    "customer": {
      "name": "Carlos Mendez",
      "email": "carlos@email.com",
      "document": { "number": "MEMC801201AB4", "type": "CURP" }
    }
  }'

Example - India (INR / UPI)

bash

curl --location 'https://baanko.app/api/transaction/create' \
  --header 'Content-Type: application/json' \
  --header 'X-Client-Id: cli_abc123' \
  --header 'X-API-Key: sk_live_xxxx' \
  --header 'Idempotency-Key: order-IN-00453' \
  --data '{
    "amount": 100000,
    "paymentMethod": "UPI",
    "currency": "INR",
    "postbackUrl": "https://yoursite.com/webhook",
    "customer": {
      "name": "Raj Kumar",
      "email": "raj@email.com"
    }
  }'

Example - Kenya (KES / M-Pesa)

bash

curl --location 'https://baanko.app/api/transaction/create' \
  --header 'Content-Type: application/json' \
  --header 'X-Client-Id: cli_abc123' \
  --header 'X-API-Key: sk_live_xxxx' \
  --header 'Idempotency-Key: order-KE-00466' \
  --data '{
    "amount": 1000000,
    "paymentMethod": "MPESA",
    "currency": "KES",
    "postbackUrl": "https://yoursite.com/webhook",
    "customer": {
      "name": "John Mwangi",
      "email": "john@email.com",
      "phone": "+254712345678"
    }
  }'

Response (200 OK)

json

{
  "data": {
    "id": "202304151647256461949132800",
    "externalRef": "usr_789",
    "amount": 25000,
    "companyId": 42,
    "paymentMethod": "PIX",
    "status": "WAITING_PAYMENT",
    "pix": {
      "brcode": "00020126580014br.gov.bcb.pix...",
      "qrcode": "data:image/png;base64,iVBORw0KGgo...",
      "txId": "202304151647256461949132800",
      "expiresAt": "2023-04-16T15:47:25Z"
    }
  },
  "status": 200,
  "message": "Transacao criada e registrada com sucesso."
}

Create Payout (Pay-out)

POSThttps://baanko.app/api/withdraw/request

Idempotency-Key is required for payouts. It ensures that retrying the same request does not create two payouts.

Example - Brazil (PIX)

bash

curl --location 'https://baanko.app/api/withdraw/request' \
  --header 'Content-Type: application/json' \
  --header 'X-Client-Id: cli_abc123' \
  --header 'X-API-Key: sk_live_xxxx' \
  --header 'Idempotency-Key: wd-BR-user789-001' \
  --data '{
    "companyId": 42,
    "amount": 5000,
    "currency": "BRL",
    "pixKey": "98765432100",
    "pixKeyType": "CPF",
    "creditorDocument": "98765432100",
    "description": "User payout"
  }'

Example - Mexico (SPEI)

bash

curl --location 'https://baanko.app/api/withdraw/request' \
  --header 'Content-Type: application/json' \
  --header 'X-Client-Id: cli_abc123' \
  --header 'X-API-Key: sk_live_xxxx' \
  --header 'Idempotency-Key: wd-MX-user790-001' \
  --data '{
    "companyId": 42,
    "amount": 80000,
    "currency": "MXN",
    "description": "Pago al usuario",
    "metadata": {
      "beneficiaryName": "Carlos Mendez",
      "accountNum": "032180000118359719",
      "bankCode": "032",
      "channel": "SPEI"
    }
  }'

Example - India (UPI)

bash

curl --location 'https://baanko.app/api/withdraw/request' \
  --header 'Content-Type: application/json' \
  --header 'X-Client-Id: cli_abc123' \
  --header 'X-API-Key: sk_live_xxxx' \
  --header 'Idempotency-Key: wd-IN-user792-001' \
  --data '{
    "companyId": 42,
    "amount": 100000,
    "currency": "INR",
    "description": "User payout",
    "metadata": {
      "beneficiaryName": "Raj Kumar",
      "vpa": "raj@oksbi",
      "channel": "UPI"
    }
  }'

Example - Kenya (M-Pesa)

bash

curl --location 'https://baanko.app/api/withdraw/request' \
  --header 'Content-Type: application/json' \
  --header 'X-Client-Id: cli_abc123' \
  --header 'X-API-Key: sk_live_xxxx' \
  --header 'Idempotency-Key: wd-KE-user794-001' \
  --data '{
    "companyId": 42,
    "amount": 50000,
    "currency": "KES",
    "description": "User payout",
    "metadata": {
      "beneficiaryName": "John Mwangi",
      "accountNum": "254712345678",
      "channel": "MPESA"
    }
  }'

Fields per Country - Pay-out (metadata)

Latin America

Country	Currency	Fields in metadata
Brazil	BRL	`pixKey, pixKeyType` (top-level)
Mexico	MXN	`beneficiaryName, accountNum (CLABE), bankCode, channel: "SPEI"`
Colombia	COP	`beneficiaryName, accountNum, bankCode, accountType, channel: "PSE"`
Argentina	ARS	`beneficiaryName, accountNum (CBU/CVU 22 digits), channel: "BANK_TRANSFER"`

Asia

Country	Currency	Fields in metadata
India (UPI)	INR	`beneficiaryName, vpa (e.g. user@oksbi), channel: "UPI"`
India (IMPS)	INR	`beneficiaryName, accountNum, ifscCode, channel: "IMPS"`
Philippines	PHP	`beneficiaryName, cardNo (GCash phone), channel: "GCASH"`
Pakistan	PKR	`beneficiaryName, accountNum, channel: "EASYPAISA" \| "JAZZCASH"`

Africa

Country	Currency	Fields in metadata
Kenya	KES	`beneficiaryName, accountNum (phone), channel: "MPESA"`
Nigeria	NGN	`beneficiaryName, accountNum (10 digits), bankCode (CBN), channel: "BANK_TRANSFER"`
Tanzania	TZS	`beneficiaryName, accountNum (phone), channel: "TIGOPESA" \| "AIRTEL"`

Status Mapping

Charge (Pay-in)

Status	Meaning	Action
`WAITING_PAYMENT`	Awaiting payment	Show the QR code / instructions
`successful`	Payment confirmed	Credit the balance / release the order
`failure`	Payment failed	Notify the user
`refunded`	Payment refunded	Reverse the credit

Payout (Pay-out)

Status	Meaning	Action
`processing`	Processing (not final)	Wait for the webhook with the final status
`successful`	Payout completed	Confirm to the user
`failure`	Payout failed (final)	Release the reserved balance. A failed payout never changes to successful
`refunded`	Payout reversed	Credit it back

Best Practices

Always use idempotency

Send an Idempotency-Key on every charge and payout. Use a unique ID from your system.

Amounts in cents

amount is always an integer in cents. R$ 10.50 = 1050, MXN 500 = 50000.

Implement the webhook

Don't rely on polling. The final status always arrives through the callback.

Only processing is temporary

processing is not final: wait for the webhook. successful, failure and refunded are final, and a payout that failed never changes to successful later.

Handle duplicate webhooks

The same event can arrive more than once. Store the processed IDs and ignore repeats.