Lookup Payment Code | SQRIL

Resolves a typed/manual payment destination or merchant / account identifier into the same decode flow as decodeQr: creates a PENDING transaction and returns tx_id.

Use this endpoint when the payer types a destination instead of scanning a QR. Scanned EMV / local QR strings should continue to use decodeQr.

Authentication

REQUIRED: Basic Auth Authorization: Basic base64(client_id:client_secret).

Two request contracts

1. Manual payment destinations (AR, BR, PE, BO, CO, NG, GH, ZM)

Required:

customer_id
country_code
payment_method — must match the corridor:
AR, BR, CO → payment_key
PE → ewallet
BO, NG, GH, ZM → bank_transfer
payment_destination — the typed destination (PIX key, phone, CBU/CVU/alias, bank account, BREB key, or NG/GH/ZM account / mobile-money number). Legacy alias: qr_string.

payment_destination_code is required for:

PE — YAPE or PLIN
BR — must be PIX
CO — must be BREB
BO — bank code (see GET /listBanks?country_code=BO)
NG / GH / ZM — bank or mobile-money network code (e.g. 058, MTN)

Bolivia-only extras when payment_method is bank_transfer:

account_type — SAVINGS or CHECKING
recipient — name_first, name_last, ic_number

Sender is never accepted on the request; it is always derived from the registered customer.

2. Merchant / account lookup (KE, TZ, VN)

Required:

customer_id
country_code — KE, TZ, or VN
merchant_id — till/paybill (KE/TZ) or bank account number (VN)

Optional:

account_reference — paybill bill reference (KE/TZ) or bank BIN (VN)

Shared optional fields

amount, currency
partner_transaction_id
partner_app_id (1–64 chars [a-zA-Z0-9_-])
wallet_identifier

Response

Same curated public shape as decodeQr (tx_id, is_dynamic, amount, country, currency, fees when amount > 0, missing_fields, etc.).

Payout flow: lookupPaymentCode → getQuotation → executePayout.

Resolves a **typed/manual payment destination** or **merchant / account identifier** into the same decode flow as `decodeQr`: creates a **PENDING** transaction and returns `tx_id`. Use this endpoint when the payer types a destination instead of scanning a QR. Scanned EMV / local QR strings should continue to use **decodeQr**. **Authentication** - **REQUIRED**: Basic Auth `Authorization: Basic base64(client_id:client_secret)`. **Two request contracts** ### 1. Manual payment destinations (AR, BR, PE, BO, CO, NG, GH, ZM) Required: - `customer_id` - `country_code` - `payment_method` — must match the corridor: - `AR`, `BR`, `CO` → `payment_key` - `PE` → `ewallet` - `BO`, `NG`, `GH`, `ZM` → `bank_transfer` - `payment_destination` — the typed destination (PIX key, phone, CBU/CVU/alias, bank account, BREB key, or NG/GH/ZM account / mobile-money number). Legacy alias: `qr_string`. `payment_destination_code` is required for: - `PE` — `YAPE` or `PLIN` - `BR` — must be `PIX` - `CO` — must be `BREB` - `BO` — bank code (see `GET /listBanks?country_code=BO`) - `NG` / `GH` / `ZM` — bank or mobile-money network code (e.g. `058`, `MTN`) Bolivia-only extras when `payment_method` is `bank_transfer`: - `account_type` — `SAVINGS` or `CHECKING` - `recipient` — `name_first`, `name_last`, `ic_number` Sender is **never** accepted on the request; it is always derived from the registered customer. ### 2. Merchant / account lookup (KE, TZ, VN) Required: - `customer_id` - `country_code` — `KE`, `TZ`, or `VN` - `merchant_id` — till/paybill (KE/TZ) or bank account number (VN) Optional: - `account_reference` — paybill bill reference (KE/TZ) or bank BIN (VN) **Shared optional fields** - `amount`, `currency` - `partner_transaction_id` - `partner_app_id` (1–64 chars `[a-zA-Z0-9_-]`) - `wallet_identifier` **Response** Same curated public shape as **decodeQr** (`tx_id`, `is_dynamic`, `amount`, `country`, `currency`, fees when amount > 0, `missing_fields`, etc.). **Payout flow:** **lookupPaymentCode** → **getQuotation** → **executePayout**.

Authentication

AuthorizationBasic

Basic Auth: base64(client_id:client_secret)

Query parameters

dpintegerOptional0-10Defaults to 2

Decimal places for monetary fields in the response (USD amounts, fees, exchange rates). Default 2, which rounds sub-cent fees to 0. Use dp=4 or higher to reconcile against exact deducted totals: at full precision amount_usd + percentage_fee + fixed_fee equals the amount deducted from your balance. Rounding is applied to the response only; all stored values and balance deductions always use full precision.

Request

This endpoint expects an object.

customer_idstringRequired

country_codestringRequired

ISO alpha-2. Required. Manual destinations: AR, BR, PE, BO, CO, NG, GH, ZM. Merchant lookup: KE, TZ, VN.

payment_methodenumOptional

Required for manual payment destinations. Must match the corridor (see endpoint description).

Allowed values:

payment_destinationstringOptional

Typed destination string for manual corridors. Legacy alias: qr_string.

payment_destination_codestringOptional

Rail or institution code: PIX, BREB, YAPE/PLIN, Bolivia bank code, or NG/GH/ZM bank/network code.

account_typeenumOptional

Bolivia bank transfers only.

Allowed values:

recipientobjectOptional

Bolivia bank transfers only.

merchant_idstringOptional

Till/paybill (KE/TZ) or bank account number (VN). Used by the merchant lookup contract.

account_referencestringOptional

Paybill bill reference (KE/TZ) or bank BIN (VN).

amountdoubleOptional

Optional local-currency amount. When > 0, pricing may be computed on the response.

currencystringOptional

Optional ISO 4217. Defaults to the corridor currency when omitted.

partner_transaction_idstringOptional

partner_app_idstringOptional

Optional partner sub-app id (1–64 chars, [a-zA-Z0-9_-]).

wallet_identifierstringOptional

qr_stringstringOptional

Legacy alias for payment_destination on manual corridors. Prefer payment_destination.

Response

OK — same shape as decodeQr

is_dynamicbooleanOptional

is_businessbooleanOptional

amountdoubleOptional

merchantstringOptional

merchant_idstringOptional

Africa (KE/TZ) till or paybill number when returned.

merchant_namestringOptional

Africa (KE/TZ) verified merchant display name when returned.

payment_typeenumOptional

Africa (KE/TZ) payment destination type when returned.

merchant_infoobjectOptional

Africa (KE/TZ) merchant metadata when returned.

countrystringOptional

tx_idstringOptional

currencystringOptional

partner_transaction_idstringOptional

amount_usddoubleOptional

feedoubleOptional

percentage_feedoubleOptional

fixed_feedoubleOptional

missing_fieldslist of maps from strings to anyOptional

suggested_valuesmap from strings to anyOptional

sendermap from strings to anyOptional

recipientmap from strings to anyOptional

Errors

400

Bad Request Error

Resolves a typed/manual payment destination or merchant / account identifier into the same decode flow as decodeQr: creates a PENDING transaction and returns tx_id.

Use this endpoint when the payer types a destination instead of scanning a QR. Scanned EMV / local QR strings should continue to use decodeQr.

Authentication

REQUIRED: Basic Auth Authorization: Basic base64(client_id:client_secret).

Two request contracts

1. Manual payment destinations (AR, BR, PE, BO, CO, NG, GH, ZM)

Required:

customer_id
country_code
payment_method — must match the corridor:
AR, BR, CO → payment_key
PE → ewallet
BO, NG, GH, ZM → bank_transfer
payment_destination — the typed destination (PIX key, phone, CBU/CVU/alias, bank account, BREB key, or NG/GH/ZM account / mobile-money number). Legacy alias: qr_string.

payment_destination_code is required for:

PE — YAPE or PLIN
BR — must be PIX
CO — must be BREB
BO — bank code (see GET /listBanks?country_code=BO)
NG / GH / ZM — bank or mobile-money network code (e.g. 058, MTN)

Bolivia-only extras when payment_method is bank_transfer:

account_type — SAVINGS or CHECKING
recipient — name_first, name_last, ic_number

Sender is never accepted on the request; it is always derived from the registered customer.

2. Merchant / account lookup (KE, TZ, VN)

Required:

customer_id
country_code — KE, TZ, or VN
merchant_id — till/paybill (KE/TZ) or bank account number (VN)

Optional:

account_reference — paybill bill reference (KE/TZ) or bank BIN (VN)

Shared optional fields

amount, currency
partner_transaction_id
partner_app_id (1–64 chars [a-zA-Z0-9_-])
wallet_identifier

Response

Same curated public shape as decodeQr (tx_id, is_dynamic, amount, country, currency, fees when amount > 0, missing_fields, etc.).

Payout flow: lookupPaymentCode → getQuotation → executePayout.

$	curl -X POST https://stg-api.sqril.io/lookupPaymentCode \
>	-H "Content-Type: application/json" \
>	-u "<username>:<password>" \
>	-d '{
>	"customer_id": "{{customer_id}}",
>	"country_code": "AR",
>	"payment_method": "payment_key",
>	"payment_destination": "4310001343800000045110"
>	}'

1	{
2	"is_dynamic": false,
3	"is_business": false,
4	"amount": 0,
5	"merchant": "",
6	"country": "AR",
7	"tx_id": "tx_1234567890_abc123",
8	"currency": "ARS",
9	"partner_transaction_id": "",
10	"missing_fields": [
11	{
12	"field": "amount",
13	"type": "numeric",
14	"label": "Amount"
15	}
16	]
17	}