Bank transfer payment provider for Latin American markets (Chile, Peru, Mexico). Chile is processed through the Fintoc bank widget on Cleo's hosted page. Supports Pay-In and Pay-Out.Operations: Pay-In ✓ | Pay-Out ✓ | Webhook ✓
Processing: Asynchronous - redirect user to Cleo's hosted page; final status via webhook
Markets: Chile (CLP), Peru (PEN), Mexico (MXN)Currency: Cleo processes only the local currency of the selected market. The currency is derived from the country you send (Chile → CLP, Peru → PEN, Mexico → MXN); Cleo returns the effective currency from its country settings, so the amount is charged in that local currency.
Fields marked with * are required.
Configuration (Mozarto back office)#
These fields are in the locked API Credentials section of the account's Processing Scope tab. Unlock it with your 2FA code first - see Unlock API credentials.
| Field | Description |
|---|
accountName * | Display name for this account |
cleoApiKey.chileApiKey * | API key for Chile (CL) transactions |
cleoApiKey.peruApiKey * | API key for Peru (PE) transactions |
cleoApiKey.mexicoApiKey * | API key for Mexico (MX) transactions |
siteUrl * | Your site URL - Cleo redirects the user here after a Pay-In. This configured value is always used; it cannot be overridden per transaction |
webhookUrl * | Your HTTPS endpoint for transaction status updates |
The correct regional API key is selected automatically from the country sent in the transaction request.
Pay-In#
POST /v1/api/mozarto/cashier
Request body#
| Field | Type | Description |
|---|
pspType * | string | Always "CLEO" |
type * | string | Always "PAYIN" |
baseamount * | number | Amount as a number (e.g. 10000) |
currency * | string | Currency code (e.g. "CLP", "PEN", "MXN"). Used only as a fallback - the effective currency is derived from country (see the currency note above) |
country * | string | Market to process the transaction in - Chile, Peru, or Mexico, as the full name, ISO 3166-1 alpha-2, or alpha-3 (e.g. "Chile", "CL", "CHL"). See Country codes. Converted to alpha-2 before being sent to Cleo, and selects the regional API key and local currency |
userId * | string | Your internal user/player identifier - also used as Cleo's customer external key |
email * | string | User's email address - used as the customer external key when userId is absent |
merchantReference | string | Your reference, echoed back in the response and webhook |
Example request#
{
"pspType": "CLEO",
"type": "PAYIN",
"baseamount": 10000,
"currency": "CLP",
"country": "Chile",
"userId": "user_123",
"email": "player@example.com",
"merchantReference": "ORDER-4821"
}
Response#
{
"status": "success",
"message": "Successfully",
"isSuccess": true,
"data": {
"status": "PENDING",
"url": "https://checkout.cleo.finance/...",
"sessionId": "60a74038-5b94-427e-8cff-abc123",
"transactionId": "64a1f2b3c4d5e6f7a8b9c0d1",
"merchantReference": "ORDER-4821",
"amount": 10000
}
}
| Field | Description |
|---|
data.url | Cleo hosted payment page URL - redirect the user here |
data.sessionId | Cleo session identifier - used to match the incoming webhook to the transaction |
data.status | Initial Cleo status - "PENDING" on creation |
data.transactionId | Mozarto transaction ID - use for status queries and idempotency |
data.merchantReference | The merchant reference passed in the request - empty string if not set |
data.amount | Transaction amount as a number |
Pay-Out#
POST /v1/api/mozarto/cashier
type set to "PAYOUT". Pay-Out is not redirect-based - no data.url is returned; the final status arrives via webhook.Response#
{
"status": "success",
"message": "Successfully",
"isSuccess": true,
"data": {
"status": "PENDING",
"sessionId": "60a74038-5b94-427e-8cff-abc123",
"transactionId": "64a1f2b3c4d5e6f7a8b9c0d1",
"merchantReference": "ORDER-4821",
"amount": 10000
}
}
Webhook#
Mozarto calls your webhookUrl when the transaction reaches a final state. Cleo notifies Mozarto on its own callback URL first; Mozarto then forwards a normalized notification to you. The payload is identical for Pay-In and Pay-Out - it carries no flow indicator. Match transaction_id against the cashier call to distinguish them.Payload example#
{
"transaction_id": "64a1f2b3c4d5e6f7a8b9c0d1",
"user_id": "000000000000000000000001",
"status": "SUCCESS",
"transaction_status": "Approved",
"message": "Transaction completed successfully",
"amount": 10000,
"merchantReference": "ORDER-4821"
}
| Field | Description |
|---|
transaction_id | Mozarto transaction ID - matches data.transactionId from the Pay-In/Pay-Out response |
user_id | The user ID from the original transaction |
status | Raw Cleo status - do not use for business logic (Pay-In success is SUCCESS, Pay-Out success is PAID) |
transaction_status | Normalized Mozarto status - "Approved" or "Declined". Use this for all business logic |
message | Human-readable description of the outcome |
amount | Transaction amount as a number |
merchantReference | The merchant reference passed in the original request - empty string if not set |
Error codes#
Cleo Pay-In transport failures are mapped to normalized Mozarto errorCode values. Use errorCode for programmatic handling rather than parsing the raw Cleo response.Mozarto errorCode | PSP raw signal | When |
|---|
INVALID_PSP_CREDENTIALS | HTTP 404 / 401 / 403 | Cleo API key (per-country) is missing, wrong, or the account is not active |
PSP_TIMEOUT | HTTP 408 or response body contains "timeout" | Cleo did not respond in time - safe to retry |
PSP_UNAVAILABLE | HTTP 5xx | Cleo service error - safe to retry with backoff |
PSP_RATE_LIMITED | HTTP 429 | Too many requests - retry after a delay |
UNKNOWN_PSP_ERROR | Any other response | Unrecognised error - check the raw response and contact support if it persists |
A country other than Chile, Peru, or Mexico (in any accepted form) is rejected before the Cleo call with an HTTP 400 and the message "Invalid country selected. Please choose either Chile, Peru, or Mexico."
For the full list of errorCode values and retryability guidance, see Errors. Modified at 2026-11-02 13:18:55
