Cleo

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)

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

The user is redirected to Cleo's hosted page (Fintoc widget for Chile) to complete the bank transfer. The final status arrives later via webhook.

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. Must be `"Chile"`, `"Peru"`, or `"Mexico"` - 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

Uses the same request body as Pay-In with 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 method field will be CLEO_PAYIN or CLEO_PAYOUT.

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 missing or invalid country (not one of Chile, Peru, Mexico) 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.

Configuration (Mozarto back office)#

Pay-In#

Request body#

Example request#

Response#

Pay-Out#

Response#

Webhook#

Payload example#

Error codes#

Configuration (Mozarto back office)

Pay-In

Request body

Example request

Response

Pay-Out

Response

Webhook

Payload example

Error codes