Payment currencies and amount scales
WhatsApp and Web Chatt accept the same content.paymentRequest structure. currency is optional and defaults to BRL. Use uppercase ISO 4217 codes. offset is optional and defaults to 100; it must match the currency's minor units. For currencies with other scales, supply offset explicitly.
| Method | Supported currencies | WhatsApp presentation | Web Chatt presentation |
|---|---|---|---|
pix | BRL only | Existing Brazil payment flow | Payment card with copy code |
boleto | BRL only | Existing Brazil payment flow | Payment card with digitable line |
payment_link with BRL | BRL | Existing Brazil payment flow | Payment card with link |
payment_link with another supported code | All codes below | CTA URL message with a payment button | Payment card formatted in the supplied currency |
The current WhatsApp integration uses Brazil order_details with payment_type: br. International links are not native WhatsApp payment cards. They use a CTA URL message with your bodyText, the order reference, the total and a localized payment button (Pagar agora by default) that opens paymentLink.url. The URL is not appended automatically as plain text. The CTA remains subject to the WhatsApp customer-service window. A later international payment update should be sent as an ordinary text reply; do not use Brazil-native orderStatus to update a CTA message. Approved templates retain their provider-specific rules.
Hub displays the supplied payment details. It does not issue payment links, convert currencies, calculate exchange rates or verify that the checkout actually charges the supplied total. Your payment provider must support the currency and the checkout must match the request. Payment capture must be confirmed by your provider.
Integer values, not always cents
For compatibility, the field names remain totalAmountCents, subtotalCents, items[].amountCents and tax.valueCents. Their values are integers in units of 1 / offset, not always hundredths. Do not send decimal values in these fields.
| Currency | Offset | Integer value | Displayed major-unit amount |
|---|---|---|---|
| BRL, USD, EUR | 100 | 10990 | 109.90 |
| JPY (Japanese yen) | 1 | 10990 | 10990 |
| KWD (Kuwaiti dinar) | 1000 | 10990 | 10.990 |
| CLF (Unidad de Fomento) | 10000 | 10990 | 1.0990 |
The same currency and root scale apply to every item, subtotal, tax and total. If supplied, tax.offset must equal the root offset; when omitted it uses the root scale. The subtotal equals the sum of unit amount multiplied by quantity. The total equals subtotal plus tax. Values and quantities must be safe integers; invalid codes, scales, method/currency combinations and inconsistent totals are rejected. For WhatsApp non-BRL links, the rendered CTA body (bodyText, order reference and total) must fit 1024 characters. Requests that exceed it are rejected; there is no fallback to ordinary text. Item, subtotal and tax data remain validated, but the CTA body displays only the total. Web Chatt keeps its existing card details and normal 4096-character bodyText limit.
Examples
Use POST /v1/communication/whatsapp/message or POST /v1/communication/web-chatt2me/message, replacing from and to for that channel. The request content is identical:
{
"from": "{{APPLICATION_CHANNEL_ID}}",
"to": "{{RECIPIENT_ID}}",
"content": {
"paymentRequest": {
"bodyText": "Pay using the link.",
"referenceId": "order-jpy-123",
"paymentMethod": "payment_link",
"paymentLink": { "url": "https://pay.example/orders/order-jpy-123" },
"currency": "JPY",
"offset": 1,
"totalAmountCents": 10990,
"subtotalCents": 10990,
"items": [
{ "retailerId": "item-1", "name": "Product", "amountCents": 10990, "quantity": 1 }
]
}
}
}
For USD or EUR, change currency and use offset: 100. For KWD use 1000; for CLF use 10000. Omitting both fields keeps the existing BRL/100 behavior. The API reference includes complete examples for each of these cases.
MCP
hub_send_whatsapp_message and hub_send_web_chatt2me_message expose the same optional content.paymentRequest.currency and offset fields. Select the authenticated organization, application and channel as usual. The tool schemas enumerate the supported codes and enforce the scale groups and BRL-only PIX/boleto rule. REST and MCP both validate totals before submission. A successful tool result is submission, not payment confirmation.
WhatsApp payment button language
Set optional content.paymentRequest.language independently of currency:
| Language | Button label |
|---|---|
pt (default) | Pagar agora |
en | Pay now |
es | Pagar ahora |
Regional forms with a two-letter region, such as pt-BR, pt-PT, en-US, en-GB, es-ES, es-MX or es-AR, select the same base-language label. Other languages are rejected rather than silently guessed. Without the field, the current Portuguese label remains.
For example, "currency": "USD", "language": "en" produces Pay now; USD without language still produces Pagar agora. Currency is not a reliable way to identify the recipient's language. This field affects the Hub-generated WhatsApp CTA button only: the supplied bodyText is preserved, BRL-native provider buttons keep their own behavior, and Web Chatt uses the visitor's selected widget language.
The same optional language field is exposed in the REST and MCP payment-request schemas. The send API reference includes an English USD payment example.
Supported codes
Snapshot: SIX ISO 4217 List One, published 2026-09-17. This release supports all 165 codes with numeric minor units in that list, including monetary fund units. Precious metals, test/no-currency codes and other entries with N.A. minor units are excluded; cryptocurrencies such as BTC are not ISO 4217 currencies. A listed code means Hub can validate and display the amount, not that every payment processor accepts it. The list is bundled with this release; it is not fetched while sending a message.
Source: SIX ISO 4217 maintenance agency, current currency and fund list (XML).
| Code | Minor-unit decimal places | Offset |
|---|---|---|
| AED | 2 | 100 |
| AFN | 2 | 100 |
| ALL | 2 | 100 |
| AMD | 2 | 100 |
| AOA | 2 | 100 |
| ARS | 2 | 100 |
| AUD | 2 | 100 |
| AWG | 2 | 100 |
| AZN | 2 | 100 |
| BAM | 2 | 100 |
| BBD | 2 | 100 |
| BDT | 2 | 100 |
| BHD | 3 | 1000 |
| BIF | 0 | 1 |
| BMD | 2 | 100 |
| BND | 2 | 100 |
| BOB | 2 | 100 |
| BOV | 2 | 100 |
| BRL | 2 | 100 |
| BSD | 2 | 100 |
| BTN | 2 | 100 |
| BWP | 2 | 100 |
| BYN | 2 | 100 |
| BZD | 2 | 100 |
| CAD | 2 | 100 |
| CDF | 2 | 100 |
| CHE | 2 | 100 |
| CHF | 2 | 100 |
| CHW | 2 | 100 |
| CLF | 4 | 10000 |
| CLP | 0 | 1 |
| CNY | 2 | 100 |
| COP | 2 | 100 |
| COU | 2 | 100 |
| CRC | 2 | 100 |
| CUP | 2 | 100 |
| CVE | 2 | 100 |
| CZK | 2 | 100 |
| DJF | 0 | 1 |
| DKK | 2 | 100 |
| DOP | 2 | 100 |
| DZD | 2 | 100 |
| EGP | 2 | 100 |
| ERN | 2 | 100 |
| ETB | 2 | 100 |
| EUR | 2 | 100 |
| FJD | 2 | 100 |
| FKP | 2 | 100 |
| GBP | 2 | 100 |
| GEL | 2 | 100 |
| GHS | 2 | 100 |
| GIP | 2 | 100 |
| GMD | 2 | 100 |
| GNF | 0 | 1 |
| GTQ | 2 | 100 |
| GYD | 2 | 100 |
| HKD | 2 | 100 |
| HNL | 2 | 100 |
| HTG | 2 | 100 |
| HUF | 2 | 100 |
| IDR | 2 | 100 |
| ILS | 2 | 100 |
| INR | 2 | 100 |
| IQD | 3 | 1000 |
| IRR | 2 | 100 |
| ISK | 0 | 1 |
| JMD | 2 | 100 |
| JOD | 3 | 1000 |
| JPY | 0 | 1 |
| KES | 2 | 100 |
| KGS | 2 | 100 |
| KHR | 2 | 100 |
| KMF | 0 | 1 |
| KPW | 2 | 100 |
| KRW | 0 | 1 |
| KWD | 3 | 1000 |
| KYD | 2 | 100 |
| KZT | 2 | 100 |
| LAK | 2 | 100 |
| LBP | 2 | 100 |
| LKR | 2 | 100 |
| LRD | 2 | 100 |
| LSL | 2 | 100 |
| LYD | 3 | 1000 |
| MAD | 2 | 100 |
| MDL | 2 | 100 |
| MGA | 2 | 100 |
| MKD | 2 | 100 |
| MMK | 2 | 100 |
| MNT | 2 | 100 |
| MOP | 2 | 100 |
| MRU | 2 | 100 |
| MUR | 2 | 100 |
| MVR | 2 | 100 |
| MWK | 2 | 100 |
| MXN | 2 | 100 |
| MXV | 2 | 100 |
| MYR | 2 | 100 |
| MZN | 2 | 100 |
| NAD | 2 | 100 |
| NGN | 2 | 100 |
| NIO | 2 | 100 |
| NOK | 2 | 100 |
| NPR | 2 | 100 |
| NZD | 2 | 100 |
| OMR | 3 | 1000 |
| PAB | 2 | 100 |
| PEN | 2 | 100 |
| PGK | 2 | 100 |
| PHP | 2 | 100 |
| PKR | 2 | 100 |
| PLN | 2 | 100 |
| PYG | 0 | 1 |
| QAR | 2 | 100 |
| RON | 2 | 100 |
| RSD | 2 | 100 |
| RUB | 2 | 100 |
| RWF | 0 | 1 |
| SAR | 2 | 100 |
| SBD | 2 | 100 |
| SCR | 2 | 100 |
| SDG | 2 | 100 |
| SEK | 2 | 100 |
| SGD | 2 | 100 |
| SHP | 2 | 100 |
| SLE | 2 | 100 |
| SOS | 2 | 100 |
| SRD | 2 | 100 |
| SSP | 2 | 100 |
| STN | 2 | 100 |
| SVC | 2 | 100 |
| SYP | 2 | 100 |
| SZL | 2 | 100 |
| THB | 2 | 100 |
| TJS | 2 | 100 |
| TMT | 2 | 100 |
| TND | 3 | 1000 |
| TOP | 2 | 100 |
| TRY | 2 | 100 |
| TTD | 2 | 100 |
| TWD | 2 | 100 |
| TZS | 2 | 100 |
| UAH | 2 | 100 |
| UGX | 0 | 1 |
| USD | 2 | 100 |
| USN | 2 | 100 |
| UYI | 0 | 1 |
| UYU | 2 | 100 |
| UYW | 4 | 10000 |
| UZS | 2 | 100 |
| VED | 2 | 100 |
| VES | 2 | 100 |
| VND | 0 | 1 |
| VUV | 0 | 1 |
| WST | 2 | 100 |
| XAD | 2 | 100 |
| XAF | 0 | 1 |
| XCD | 2 | 100 |
| XCG | 2 | 100 |
| XOF | 0 | 1 |
| XPF | 0 | 1 |
| YER | 2 | 100 |
| ZAR | 2 | 100 |
| ZMW | 2 | 100 |
| ZWG | 2 | 100 |