Skip to main content
Version: 1.0

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.

MethodSupported currenciesWhatsApp presentationWeb Chatt presentation
pixBRL onlyExisting Brazil payment flowPayment card with copy code
boletoBRL onlyExisting Brazil payment flowPayment card with digitable line
payment_link with BRLBRLExisting Brazil payment flowPayment card with link
payment_link with another supported codeAll codes belowCTA URL message with a payment buttonPayment 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.

CurrencyOffsetInteger valueDisplayed major-unit amount
BRL, USD, EUR10010990109.90
JPY (Japanese yen)11099010990
KWD (Kuwaiti dinar)10001099010.990
CLF (Unidad de Fomento)10000109901.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:

LanguageButton label
pt (default)Pagar agora
enPay now
esPagar 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).

CodeMinor-unit decimal placesOffset
AED2100
AFN2100
ALL2100
AMD2100
AOA2100
ARS2100
AUD2100
AWG2100
AZN2100
BAM2100
BBD2100
BDT2100
BHD31000
BIF01
BMD2100
BND2100
BOB2100
BOV2100
BRL2100
BSD2100
BTN2100
BWP2100
BYN2100
BZD2100
CAD2100
CDF2100
CHE2100
CHF2100
CHW2100
CLF410000
CLP01
CNY2100
COP2100
COU2100
CRC2100
CUP2100
CVE2100
CZK2100
DJF01
DKK2100
DOP2100
DZD2100
EGP2100
ERN2100
ETB2100
EUR2100
FJD2100
FKP2100
GBP2100
GEL2100
GHS2100
GIP2100
GMD2100
GNF01
GTQ2100
GYD2100
HKD2100
HNL2100
HTG2100
HUF2100
IDR2100
ILS2100
INR2100
IQD31000
IRR2100
ISK01
JMD2100
JOD31000
JPY01
KES2100
KGS2100
KHR2100
KMF01
KPW2100
KRW01
KWD31000
KYD2100
KZT2100
LAK2100
LBP2100
LKR2100
LRD2100
LSL2100
LYD31000
MAD2100
MDL2100
MGA2100
MKD2100
MMK2100
MNT2100
MOP2100
MRU2100
MUR2100
MVR2100
MWK2100
MXN2100
MXV2100
MYR2100
MZN2100
NAD2100
NGN2100
NIO2100
NOK2100
NPR2100
NZD2100
OMR31000
PAB2100
PEN2100
PGK2100
PHP2100
PKR2100
PLN2100
PYG01
QAR2100
RON2100
RSD2100
RUB2100
RWF01
SAR2100
SBD2100
SCR2100
SDG2100
SEK2100
SGD2100
SHP2100
SLE2100
SOS2100
SRD2100
SSP2100
STN2100
SVC2100
SYP2100
SZL2100
THB2100
TJS2100
TMT2100
TND31000
TOP2100
TRY2100
TTD2100
TWD2100
TZS2100
UAH2100
UGX01
USD2100
USN2100
UYI01
UYU2100
UYW410000
UZS2100
VED2100
VES2100
VND01
VUV01
WST2100
XAD2100
XAF01
XCD2100
XCG2100
XOF01
XPF01
YER2100
ZAR2100
ZMW2100
ZWG2100