> For the complete documentation index, see [llms.txt](https://docs.pagsmile.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pagsmile.com/reference/payout/scan-to-pay.md).
# Scan to Pay
##
```mermaid
%%{init: {"themeVariables": {"actorBkg": "#E5E7EB", "actorBorder": "#9CA3AF", "actorTextColor": "#111827"}, "sequence": {"mirrorActors": true}}}%%
sequenceDiagram
autonumber
participant Customer as Overseas Customer
participant Client
participant Pagsmile
participant Merchant as Local Merchant
rect rgb(235, 246, 255)
Note over Customer,Merchant: Phase 1: Scan and Retrieve QR Code Data
Merchant->>Customer: Present a local QR code
Customer->>Client: Scan the complete QR code
Client->>Pagsmile: POST /api/payout/bank-account-list
Pagsmile-->>Client: Return recipient data and scan_id
Client-->>Customer: Display the recipient and amount
end
rect rgb(255, 248, 235)
Note over Customer,Merchant: Phase 2: Confirm and Submit the Payout
Customer->>Client: Confirm the payment
Client->>Pagsmile: POST /api/payout with the QR code and scan_id
Pagsmile-->>Client: Return the request acceptance status
Pagsmile->>Merchant: Pay the local merchant in local currency via the real-time settlement network
end
rect rgb(235, 252, 235)
Note over Customer,Merchant: Phase 3: Receive the Final Result
Pagsmile-->>Client: Send the final status to notify_url
Client-->>Customer: Display the final payment result
end
```
Scan to Pay is a Pagsmile solution that enables overseas users to pay local merchants in local currency by scanning supported interoperable local QR codes with an overseas wallet or banking application. Payments are processed through the applicable real-time settlement network.
### Supported Countries and QR Schemes
Scan to Pay currently supports five countries and local QR schemes:
| Country | Local QR Scheme | Country Code | Local Currency |
| ----------- | --------------- | ------------ | -------------- |
| Brazil | Pix | `BRA` | `BRL` |
| Colombia | Bre-B | `COL` | `COP` |
| Peru | CCE QR | `PER` | `PEN` |
| Philippines | QR Ph | `PHL` | `PHP` |
| Russia | SBP QR | `RUS` | `RUB` |
Support for additional countries and local QR schemes is under development.
### How It Works
1. The local merchant presents a local QR code.
2. The overseas customer scans the QR code using the Client's wallet or banking application.
3. The Client sends the complete QR code payload to the Retrieve QR Code Data API. Pagsmile returns the recipient information, encoded amount—if available—and a one-time `scan_id`.
4. The Client displays the payment details and, after the customer confirms, submits the payout using the same QR code payload and `scan_id`.
5. Pagsmile processes the payment through the applicable real-time settlement network to the merchant in local currency, and sends the final status to `notify_url`.
{% hint style="warning" %}
The `scan_id` is short-lived and can be used only once. Submit the payout immediately after retrieving it. If it expires or has already been used, retrieve the QR code data again to obtain a new `scan_id`.
{% endhint %}
### Country Limits and Requirements
| Country | `source_currency` | `arrival_currency` | Amount | QR Code Payload (`account`) | Additional Requirements |
| ----------- | -------------------------------------------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Brazil | One of: `USD`, `EUR`, `GBP`, `BRL` | Fixed value: `BRL` | From `0.01` to `15,000 BRL`; up to 2 decimal places | Complete QR code payload; maximum 255 characters | `name`, `document_type` and `document_id` are required. |
| Colombia | One of: `USD`, `EUR`, `GBP` | Fixed value: `COP` | From `1,000` to `2,000,000 COP`; up to 2 decimal places | Complete QR code payload; maximum 600 characters | No additional recipient fields are required. |
| Peru | One of: `USD`, `EUR`, `GBP`, `PEN` | Fixed value: `PEN` | From `0.01` to `500,000 PEN`; up to 2 decimal places | Complete QR code payload; maximum 255 characters | Processing availability is subject to the receiving bank's cut-off schedule. See Peru Bank Cut-off Schedule. |
| Philippines | One of: `USD`, `EUR`, `GBP`, `PHP` | Fixed value: `PHP` | From `1` to `50,000 PHP`; up to 2 decimal places | Complete QR code payload; maximum 255 characters | No additional recipient fields are required. |
| Russia | Use a source currency enabled for the merchant account. Use `RUB` for same-currency payouts. | Fixed value: `RUB` | Must match the retrieved fixed amount, when present; up to 2 decimal places. Other network and merchant limits may apply. | Complete `https://qr.nspk.ru/...` URL used during retrieval | No additional recipient fields are required. |
### Authentication
Both endpoints on this page use the payout API authentication method described in [Security](https://docs.pagsmile.com/reference/payout/security).
1. Obtain the `AppId` and `app_key` from the merchant dashboard.
2. Sort the non-empty top-level request body parameters by parameter name in ascending order.
3. Concatenate the parameters as `key=value` pairs joined by `&`.
4. Append the `app_key` directly to the sorted parameter string.
5. Calculate the SHA-256 hash and send the lowercase hexadecimal result in the `Authorization` header.
The source IP address must also be included in the merchant's IP whitelist.
***
### Retrieve QR Code Data
Use this endpoint to validate a QR code and retrieve the recipient information required to submit a Scan to Pay payout.
`POST` `https://sandbox.transfersmile.com/api/payout/bank-account-list`
#### Headers
| Name | Type | Required | Description |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------- |
| Content-Type | string | Yes | Fixed value: `application/json; charset=UTF-8`. |
| AppId | string | Yes | Your App ID in the Pagsmile payout platform. |
| Authorization | string | Yes | Lowercase SHA-256 signature generated from the request body and your `app_key`. |
#### Request Body
| Name | Type | Required | Constraints | Description |
| ------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| country | string | Yes | One of: `BRA`, `COL`, `PER`, `PHL`, `RUS` | Recipient country code. |
| method | string | Yes | Fixed value: `QRCODE` | Payout method. |
| account\_type | string | Yes | Fixed value: `QRCODE` | Recipient account type. |
| account | string | Yes | Send the complete, unmodified QR code payload. Country-specific length constraints apply. | QR code payload captured by the scanner. For Russia, send the complete `https://qr.nspk.ru/...` URL. |
| timestamp | integer | Yes | Current Unix timestamp in seconds. Requests more than 15 seconds before or after server time are rejected. | Request timestamp. |
| buyer\_id | string | No | Maximum length: 200 characters. | Unique customer ID in the merchant system. |
| email | string | No | Valid email address; maximum length: 200 characters. | Customer email address. |
#### Request Samples
{% tabs %}
{% tab title="Brazil" %}
```json
{
"country": "BRA",
"method": "QRCODE",
"account_type": "QRCODE",
"account": "00020101021226880014br.gov.bcb.pixqrcode.com.br/pix/2e731667****",
"timestamp": 1784010600,
"buyer_id": "buyer_****",
"email": "test@example.com"
}
```
{% endtab %}
{% tab title="Colombia" %}
```json
{
"country": "COL",
"method": "QRCODE",
"account_type": "QRCODE",
"account": "00020101021226310014CO.COM.RBM.LLA0409@000********",
"timestamp": 1784010600,
"buyer_id": "buyer_****",
"email": "test@example.com"
}
```
{% endtab %}
{% tab title="Peru" %}
```json
{
"country": "PER",
"method": "QRCODE",
"account_type": "QRCODE",
"account": "0002015802PE26560032a5148da7d6f04b7e8e96c91bdbc85cb30116Plin****",
"timestamp": 1784010600,
"buyer_id": "buyer_****",
"email": "test@example.com"
}
```
{% endtab %}
{% tab title="Philippines" %}
```json
{
"country": "PHL",
"method": "QRCODE",
"account_type": "QRCODE",
"account": "00020101021127781111com.p2pqrpay********",
"timestamp": 1784010600,
"buyer_id": "buyer_****",
"email": "test@example.com"
}
```
{% endtab %}
{% tab title="Russia" %}
```json
{
"country": "RUS",
"method": "QRCODE",
"account_type": "QRCODE",
"account": "https://qr.nspk.ru/AS1A001PK5CQ92V88BFQC81JRET6A8G5",
"timestamp": 1789122513,
"buyer_id": "buyer_****",
"email": "test@example.com"
}
```
{% endtab %}
{% endtabs %}
#### Response Samples
{% tabs %}
{% tab title="Brazil" %}
```json
{
"code": 200,
"msg": "success",
"time": 1784010601,
"data": [
{
"name": "Pagsmile Test LTDA",
"document_id": "59*****85",
"document_type": "CNPJ",
"bank_code": "1*****5",
"bank_name": "MAGEN IP",
"bank_number": "1*****5",
"account": "*****",
"account_type": "PAYMENT",
"amount": "0.03",
"mcc": "5411",
"scan_id": "QH2026**************************",
"qrcode_type": "DYNAMIC_INSTANT_PAYMENT"
}
]
}
```
{% endtab %}
{% tab title="Colombia" %}
```json
{
"code": 200,
"msg": "success",
"time": 1784010601,
"data": [
{
"name": "PG*** PA*** CO***",
"document_id": "",
"document_type": "",
"bank_code": "",
"bank_name": "",
"bank_number": "",
"account": "",
"account_type": "",
"amount": "1000.00",
"scan_id": "QH2026**************************",
"qrcode_type": "DYNAMIC_INSTANT_PAYMENT"
}
]
}
```
{% endtab %}
{% tab title="Peru" %}
```json
{
"code": 200,
"msg": "success",
"time": 1784010601,
"data": [
{
"name": "LI*** EL*** QU*** PA***",
"document_id": "47****35",
"document_type": "DNI",
"bank_code": "",
"bank_name": "YAPE",
"bank_number": "",
"account": "00********18",
"account_type": "",
"amount": "",
"scan_id": "QH2026**************************",
"qrcode_type": "STATIC"
}
]
}
```
{% endtab %}
{% tab title="Philippines" %}
```json
{
"code": 200,
"msg": "success",
"time": 1784010601,
"data": [
{
"name": "Pagsmile Test",
"document_id": "",
"document_type": "",
"bank_code": "PAPHPHM1XXX",
"bank_name": "PayMaya",
"bank_number": "",
"account": "6**********2",
"account_type": "",
"amount": "",
"scan_id": "QH2026**************************",
"qrcode_type": "DYNAMIC_INSTANT_PAYMENT"
}
]
}
```
{% endtab %}
{% tab title="Russia" %}
```json
{
"code": 200,
"msg": "success",
"time": 1789122514,
"data": [
{
"name": "",
"document_id": "",
"document_type": "",
"bank_code": "",
"bank_name": "Фонд Константина Хабенского",
"bank_number": "",
"account": "100000000007",
"account_type": "",
"amount": "100",
"scan_id": "QH2026**************************",
"qrcode_type": "STATIC"
}
]
}
```
{% endtab %}
{% endtabs %}
***
### Submit a Payout
Use this endpoint to submit a payout using the same QR code payload and the `scan_id` returned by the Retrieve QR Code Data API.
`POST` `https://sandbox.transfersmile.com/api/payout`
#### Headers
| Name | Type | Required | Description |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------- |
| Content-Type | string | Yes | Fixed value: `application/json; charset=UTF-8`. |
| AppId | string | Yes | Your App ID in the Pagsmile payout platform. |
| Authorization | string | Yes | Lowercase SHA-256 signature generated from the request body and your `app_key`. |
#### Request Body
| Name | Type | Required | Constraints | Description |
| ------------------ | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| amount | number | Yes | Must be greater than zero and contain no more than 2 decimal places. Country-specific limits apply. | Payout amount. If the QR code contains a fixed amount, this value must match the retrieved amount. |
| amount\_type | string | No | One of: `source_amount`, `arrival_amount`. Default: `arrival_amount`. | Indicates whether `amount` is denominated in the merchant's source currency or the recipient's arrival currency. |
| source\_currency | string | Yes | Must be enabled for the merchant account and payout route. | Currency debited from the merchant balance. |
| arrival\_currency | string | Yes | Fixed by country. | Currency credited to the local QR recipient. |
| fee\_bear | string | Yes | One of: `merchant`, `beneficiary` | Specifies whether the merchant or beneficiary bears the payout fee. |
| account | string | Yes | Must be the complete QR code payload used to retrieve the `scan_id`. | Local payment QR code payload. |
| account\_type | string | Yes | Fixed value: `QRCODE` | Recipient account type. |
| scan\_id | string | Yes | One-time identifier generated by Pagsmile; maximum stored length: 32 characters. Use it immediately after retrieval. | Links the payout to the verified QR code data. |
| custom\_code | string | Yes | Maximum length: 50 characters; must be unique for the merchant. | Merchant-side payout order ID. |
| notify\_url | string | Yes | Valid URL; maximum length: 255 characters. | URL that receives the asynchronous final payout result. |
| method | string | Yes | Fixed value: `QRCODE` | Payout method. |
| additional\_remark | string | Yes | 4–40 characters. Only letters, numbers, spaces and underscores are supported. | Payout remark or descriptor. |
| country | string | Yes | One of: `BRA`, `COL`, `PER`, `PHL`, `RUS` | Recipient country code. |
| name | string | Conditional | 2–100 characters. For CPF recipients, use English letters and spaces. For CNPJ recipients, English letters, numbers, dots, hyphens and spaces are supported. | Recipient name returned by the Retrieve QR Code Data API. Required when `country` is `BRA`. |
| document\_type | string | Conditional | One of: `CPF`, `CNPJ` | Recipient identification type returned by the Retrieve QR Code Data API. Required when `country` is `BRA`. |
| document\_id | string | Conditional | Maximum length: 24 characters. | Recipient identification number returned by the Retrieve QR Code Data API. Required when `country` is `BRA`. |
| email | string | No | Valid email address. | Optional recipient email for Brazil. |
| phone | string | No | Maximum length: 15 characters; valid phone number. | Optional recipient phone number for Brazil. |
#### Request Samples
{% tabs %}
{% tab title="Brazil" %}
```json
{
"name": "Pagsmile Test LTDA",
"document_id": "59*****85",
"document_type": "CNPJ",
"amount": 150,
"amount_type": "arrival_amount",
"source_currency": "BRL",
"arrival_currency": "BRL",
"fee_bear": "merchant",
"account": "00020101021226880014br.gov.bcb.pixqrcode.com.br/pix/2e731667****",
"account_type": "QRCODE",
"scan_id": "QH2026**************************",
"custom_code": "custom_code_bra_********",
"notify_url": "https://sandbox.transfersmile.com/api/notify/demo",
"method": "QRCODE",
"additional_remark": "scan_to_pay_test",
"country": "BRA"
}
```
{% endtab %}
{% tab title="Colombia" %}
```json
{
"amount": 1000,
"amount_type": "arrival_amount",
"source_currency": "USD",
"arrival_currency": "COP",
"fee_bear": "merchant",
"account": "00020101021226310014CO.COM.RBM.LLA0409@000********",
"account_type": "QRCODE",
"scan_id": "QH2026**************************",
"custom_code": "custom_code_col_********",
"notify_url": "https://sandbox.transfersmile.com/api/notify/demo",
"method": "QRCODE",
"additional_remark": "scan_to_pay_test",
"country": "COL"
}
```
{% endtab %}
{% tab title="Peru" %}
```json
{
"amount": 1000,
"amount_type": "arrival_amount",
"source_currency": "PEN",
"arrival_currency": "PEN",
"fee_bear": "merchant",
"account": "0002015802PE26560032a5148da7d6f04b7e8e96c91bdbc85cb30116Plin****",
"account_type": "QRCODE",
"scan_id": "QH2026**************************",
"custom_code": "custom_code_per_********",
"notify_url": "https://sandbox.transfersmile.com/api/notify/demo",
"method": "QRCODE",
"additional_remark": "scan_to_pay_test",
"country": "PER"
}
```
{% endtab %}
{% tab title="Philippines" %}
```json
{
"amount": 100,
"amount_type": "arrival_amount",
"source_currency": "PHP",
"arrival_currency": "PHP",
"fee_bear": "merchant",
"account": "00020101021127781111com.p2pqrpay********",
"account_type": "QRCODE",
"scan_id": "QH2026**************************",
"custom_code": "custom_code_phl_********",
"notify_url": "https://sandbox.transfersmile.com/api/notify/demo",
"method": "QRCODE",
"additional_remark": "scan_to_pay_test",
"country": "PHL"
}
```
{% endtab %}
{% tab title="Russia" %}
```json
{
"amount": 100,
"amount_type": "arrival_amount",
"source_currency": "RUB",
"arrival_currency": "RUB",
"fee_bear": "merchant",
"account": "https://qr.nspk.ru/AS1A001PK5CQ92V88BFQC81JRET6A8G5",
"account_type": "QRCODE",
"scan_id": "QH2026**************************",
"custom_code": "custom_code_rus_********",
"notify_url": "https://sandbox.transfersmile.com/api/notify/demo",
"method": "QRCODE",
"additional_remark": "scan_to_pay_test",
"country": "RUS"
}
```
{% endtab %}
{% endtabs %}
#### Response
```json
{
"code": 200,
"msg": "success",
"time": 1789122520,
"data": {
"id": "TS2026****************",
"custom_code": "custom_code_rus_********",
"arrival_amount": "100.00",
"arrival_currency": "RUB",
"source_amount": "100.00",
"source_currency": "RUB",
"status": "IN_PROCESSING"
}
}
```
{% hint style="warning" %}
`IN_PROCESSING` is not a final result. Use the notification sent to `notify_url` to determine whether the payout is `PAID` or `REJECTED`. Where refunds are supported, the callback may also report `REFUNDED` or `PARTIAL_REFUNDED`.
{% endhint %}
#### Error Responses
| Code | Message |
| --------- | --------------------------------------------------- |
| `400` | `Invalid QR Code` |
| `4001015` | `account is blocked` |
| `4001020` | `order already existed` |
| `4001320` | `amount does not match the scanned QR code amount.` |
| `4001321` | `invalid scan_id. Please scan the QR code again.` |
| `4004003` | `permission denied` |
| `4004029` | `too many requests` |
| `5001000` | `system error` |
| `5001003` | `fee not configured` |
| `5001102` | `balance insufficient` |
| `5001320` | `unable to verify scan_id. Please try again later.` |
***
### Country-specific Processing Information
#### Peru Bank Cut-off Schedule
Processing availability for Scan to Pay payouts in Peru varies by receiving bank. The schedule below is provided in English and applies only when `country` is `PER` and `arrival_currency` is `PEN`.
{% hint style="info" %}
“No cut-off” means the schedule does not define an unavailable period. “No service” means processing is unavailable for the stated period. A dash (`—`) means no schedule was provided. Times are reproduced from the processing schedule.
{% endhint %}
| Bank | Monday–Friday | Weekends and Holidays |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| BCP | 03:59 p.m.–04:01 p.m.
08:46 p.m.–08:51 p.m. (variable; no longer than 6 minutes)
01:00 a.m.–02:00 a.m. (variable; no longer than 1 hour)
| No general cut-off.
Sunday: 08:46 p.m.–08:51 p.m. (variable; no longer than 6 minutes)
Saturday: 01:00 a.m.–02:00 a.m. (variable; no longer than 1 hour)
|
| Interbank | 12:00 a.m.–01:00 a.m. | No cut-off |
| Citibank | Monday–Friday: 06:00 p.m.–08:00 a.m. (D+1) | No service |
| Scotiabank | Monday: 03:50 p.m.–04:05 p.m.; 11:10 p.m.–11:30 p.m.
Tuesday–Friday: 01:30 a.m.–03:00 a.m.; 03:50 p.m.–04:05 p.m.; 11:10 p.m.–11:30 p.m.
| Saturday: 01:30 a.m.–03:00 a.m.; 11:10 p.m.–11:30 p.m.
Sunday and holidays: 01:30 a.m.–03:00 a.m. The cut-off applies when preceded by a business day, including Saturday.
|
| BBVA Continental | 09:40 p.m.–10:00 p.m. | No cut-off |
| Banco de la Nación | — | — |
| Banco de Comercio | No cut-off | No cut-off |
| Banco Pichincha | 10:30 p.m.–11:00 p.m.
02:00 a.m.–02:30 a.m.
| 10:30 p.m.–11:00 p.m.
02:00 a.m.–02:30 a.m.
|
| BanBif | 11:30 p.m.–11:40 p.m.
03:00 a.m.–03:10 a.m.
| 11:30 p.m.–11:40 p.m.
03:00 a.m.–03:10 a.m.
|
| Crediscotia | 12:00 a.m.–04:30 a.m.
03:35 p.m.–04:05 p.m.
09:00 p.m.–12:00 a.m.
| No service |
| MiBanco | Outgoing: 06:00 p.m.–08:00 a.m.
Incoming: 08:30 p.m.–06:00 a.m.
| Sunday and holidays: no service.
Saturday outgoing: 01:00 p.m.–12:00 a.m.
Saturday incoming: 08:30 p.m.–12:00 a.m.
|
| Banco GNB | No cut-off | No cut-off |
| Banco Falabella | 11:45 p.m.–12:15 a.m. | 11:45 p.m.–12:15 a.m. |
| Banco Ripley | 10:00 p.m.–01:00 a.m. on the following day | 10:00 p.m.–01:00 a.m. on the following day |
| Banco Santander | 07:00 a.m.
09:00 p.m.
| Unavailable |
| Alfin Banco | No cut-off | No cut-off |
| Compartamos Financiera | 11:00 p.m.–06:00 a.m. | 11:00 p.m.–06:00 a.m. |
| Financiera Oh | No cut-off | No cut-off |
| Financiera Efectiva | Sign-off: 11:30 p.m.
Sign-on: 06:00 a.m.
| Sign-off: 11:30 p.m.
Sign-on: 06:00 a.m.
|
| Financiera Confianza | — | — |
| Prexpe | Available 24/7 | Available 24/7 |
| Caja Metropolitana | — | — |
| Caja Piura | 12:00 a.m.–12:30 a.m.
04:00 a.m.–04:30 a.m.
| Sign-on: 06:00 a.m. |
| Caja Trujillo | 04:00 p.m.–04:05 p.m.
10:00 p.m.–12:00 a.m.
| 04:00 p.m.–04:05 p.m.
10:00 p.m.–12:00 a.m.
|
| Caja Arequipa | 12:00 a.m.–08:00 a.m. | 12:00 a.m.–08:00 a.m. |
| Caja Sullana | — | — |
| Caja Cusco | 11:30 p.m.–05:00 a.m. on the following day | 11:30 p.m.–05:00 a.m. on the following day |
| Caja Huancayo | 12:00 a.m.–02:00 a.m. (variable; approximately 2 hours) | 12:00 a.m.–02:00 a.m. (variable; approximately 2 hours) |
| Caja Ica | 11:45 p.m.–12:15 a.m. on the following day | 11:45 p.m.–12:15 a.m. on the following day |
| Caja Los Andes | — | — |
| Cooperativa ABACO | — | — |
| Tarjetas Peruanas - LIGO | — | — |
| DALE | Available 24/7 | Available 24/7 |