Introduction
Welcome to the Zippy API! Our API allows you to interact with Zippy’s payment system by creating PayIn and PayOut requests through dedicated endpoints.
You can find usage examples on the right-hand side of this page.
PayIn
PayIn is available in a specific set of countries. The availability of payment methods varies by country, with some methods supported in more countries than others.
PayIn allows to operate with the following countries:
- 🇨🇱 Chile (CL)
- 🇵🇪 Peru (PE)
- 🇦🇷 Argentina (AR)
- 🇧🇴 Bolivia (BO)
- 🇧🇷 Brazil (BR)
- 🇪🇨 Ecuador (EC)
- 🇨🇴 Colombia (CO)
- 🇵🇦 Panamá (PA)
- 🇬🇹 Guatemala (GT)
- 🇨🇷 Costa Rica (CR)
- 🇲🇽 Mexico (MX)
- 🇵🇾 Paraguay (PY)
- 🇺🇾 Uruguay (UY)
- 🇸🇻 El Salvador (SV)
- 🇭🇳 Honduras (HN)
- 🇩🇴 República Dominicana (DO)
- 🇹🇹 Trinidad y Tobago (TT)
- 🇳🇮 Nicaragua (NI)
Methods
Zippy supports multiple PayIn methods, and their availability varies by country. Use this table to identify which payment methods are currently supported in each country.
All methods listed below refer to PayIn operations.
| Method | Supported Countries |
|---|---|
| bankCard | CL, PE, AR, BO, BR, EC, CO, PA, GT, CR, MX, PY, UY, SV, HN, DO, TT, NI |
| bankTransfer | CL, PE, AR, EC, CO, PY |
| cash | PE, EC, CO, PA, GT, CR |
| mach | CL |
| wallet | BO, CO |
| mobileMoney | EC |
| transfiya | CO |
| binancepay | AR |
| pix | BR |
| SPEI | MX |
| fri | GT |
Request
Test Environment
https://api-dot-zippy-dev-payments.rj.r.appspot.com/pay
Parameters
Example:
curl --location --request POST 'https://api-dot-zippy-dev-payments.rj.r.appspot.com/pay' \
--header 'Content-Type: application/json' \
--data-raw '{
"merchantId":"2021merchant-8Z3D",
"transactionId":"Tx9bA3gPZkLr7tVf2eQm",
"country":"CL",
"currency":"CLP",
"payMethod":"bankTransfer",
"documentId":"12345678K",
"amount":"1290.00",
"email":"john.doe@gmail.com",
"name":"John Doe,
"timestamp":"1611937099",
"payinExpirationTime": "240",
"url_OK": "https://caseSuccessful.com",
"url_ERROR":"https://caseError.com”,
"objData":{
phone: "+56987654321"
}
}'
| Field | Description | Type | Required | Examples |
|---|---|---|---|---|
| merchantId | The code assigned to your merchant | string | yes | 2021merchant-02Z3D |
| transactionId | Unique ID for the PayIn reques | string | yes | Tx9bA3gPZkLr7tVf2eQm |
| country | Country code for the PayIn request (ISO 3166-1 alpha-2) | string | yes | CL |
| currency | Currency type (ISO 4217) | string | yes | CLP |
| payMethod | Specify the way of payment. Subject to availability by country | string | yes | bankTransfer |
| documentId | National identification number (without points or dashes) | string | yes | 12345678K |
| amount | Amount to pay. Only one decimal point is allowed with two decimal places | string | yes | 1290.00 |
| Customer email | string | yes | john.doe@email.com | |
| name | Customer full name | string | yes | John Doe |
| timestamp | Date in timestamp format | string | yes | 1611937099 |
| payinExpirationTime | Payment expiration time, specified in minutes | string | yes | 240 |
| url_OK | URL where the customer will be redirected after a successful payment | string | yes | Example: https://caseSuccessful.com |
| url_ERROR | URL where the customer will be redirected if the payment fails | string | yes | Example: https://caseError.com |
| objData | Additional fields if required | json | yes | { foo: "bar"} |
| objData.phone | Some providers may require it, so we recommend always including it to avoid issues. The number should follow the E.164 international format and may be necessary for EC, BO, CO. | string | conditional | +5930999000000 |
Response Parameters
| Field | Description |
|---|---|
| status | Indicates the result of the request. Possible values: "ok" or "error". |
| url | Payment URL provided by the payment method. The customer must be redirected to this URL. |
| description | Returned only when status = "error". Contains a detailed description of the error. |
Callback
After our system processes a /pay request, a callback will be sent to the merchant’s REST API. This callback includes a MD5 signature following a predefined format for validation.
| Field | Description | Type |
|---|---|---|
| AMOUNT | Payment amount as a string. | String |
| MERCHANTREQUESTID | The unique request ID provided by the merchant’s system. | String |
| CODE | Transaction result code: 0 = Validated - 12 = Error | Integer |
| MESSAGE | Message that shows if the transaction was successful or failed. | String |
| SIGN | MD5 signature generated following a predefined format for data integrity validation. | String |
| ZIPPYID | Internal transaction ID assigned by Zippy. | String |
PayOut
PayOut is available only in a specific set of countries. The availability of this service depends on the withdrawal method supported in each country.
Below is the list of countries where PayOut operations are currently supported:
- 🇨🇱 Chile (CL)
- 🇵🇪 Peru (PE)
- 🇦🇷 Argentina (AR)
- 🇪🇨 Ecuador (EC)
- 🇨🇴 Colombia (CO)
- 🇬🇹 Guatemala (GT)
- 🇲🇽 Mexico (MX)
Methods
Each country supports specific withdrawal methods based on local payment infrastructure.
All methods listed below refer to PayOut operations.
| Method | Supported Countries |
|---|---|
| bankTransfer | CL, PE, EC, CO, GT |
| wallet | CO |
| binancepay | AR |
| cbucvu | AR |
| SPEI | MX |
Before Starting
Our PayOut service uses JWT tokens signed with the RSA SHA-256 algorithm to secure every transaction.
- Step 1: Generate RSA Keys. If you haven’t created your private and public keys yet, follow the commands on the right-hand side.
RS256 Private and Public key Generation
ssh-keygen -t rsa -b 4096 -m PEM -f jwtRS256.key
# Don't add passphrase
openssl rsa -in jwtRS256.key -pubout -outform PEM -out jwt{MERCHANT_NAME}.pem
cat jwtRS256.key
cat jwt{MERCHANT_NAME}.pem
- Step 2: Generate the JWT Token. Before sending the POST request, generate the JWT using the RS256 algorithm.
javascript
npm install jsonwebtoken
const TRANSACTIONID = '21'
const AMOUNT = '5000.00'
const privateKey = fs.readFileSync('private.key');
const token = jwt.sign({ id: TRANSACTIONID, amount: AMOUNT }, privateKey, { algorithm: 'RS256' });
Step 3: JWT Payload. The payload must include the fields id and AMOUNT.
Step 4: Signature Algorithm. The signature algorithm must always be set to 'RS256'.
Get PayOut Params
Before generating a PayOut, it is necessary to retrieve three parameters that will be included along with the other required fields in the request.
POST Method
https://api-dot-zippy-dev-payments.rj.r.appspot.com/getPayOutParams
Example:
curl --location --request POST 'https://api-dot-zippy-dev-payments.rj.r.appspot.com/getPayOutParams' \
--header 'Content-Type: application/json' \
--data-raw '{
"country":"PE",
"merchantId":"2024-merchant-9x4a"
}'
| Parameter | Description | Type | example: the possible domain of required field |
|---|---|---|---|
| country | ISO 3166-1 alpha-2 country code where the PayOut request will be made. | string | PE |
| merchantId | Merchant ID assigned by Zippy. | string | 2024-merchant-9x4a |
| payoutMethod | (Optional) Required if the method is not banktransfer. If omitted, the request will be processed as a bank transfer by default. | string | bankTransfer |
Response Parameters
Output Example
{
"bankList": [
{
"bankName": "Banco Continental",
"bankId": "Banco Continental"
},
{
"bankId": "Banco de Credito",
"bankName": "Banco de Credito"
},
{
"bankName": "Interbank",
"bankId": "Interbank"
},
{
"bankName": "Scotiabank",
"bankId": "Scotiabank"
}
],
"typeAccount": [
{
"type": "Cuenta Corriente",
"typeAccountId": "0"
},
{
"typeAccountId": "1",
"type": "Cuenta Ahorro"
}
],
"customerId": [
{
"typeDocumentId": "1",
"id": "DNI"
},
{
"typeDocumentId": "2",
"id": "PAS"
},
{
"typeDocumentId": "3",
"id": "CE"
},
{
"typeDocumentId": "4",
"id": "RUC"
}
]
}
| Parameter | Description | Type |
|---|---|---|
| bankList | Array of available banks for beneficiary accounts. The required field for the PayOut service is bankId. | array |
| typeAccount | Array of supported bank account types for beneficiaries. The required field for the PayOut service is typeAccountId. | array |
| customerId | Array of beneficiary identification document types. The required field for the PayOut service is typeDocumentId. | array |
Request
In the POST request, include the previously generated JWT in the Authorization header using the standard Bearer prefix (note the space after the prefix). See the example.
To validate the JWT, you must provide the public key file jwt{MERCHANT_NAME}.pem that was generated earlier.
Example:
Authorization: "Bearer " + token
Authorization: "Bearer eyJhbGciOiJSUzI1HiIsInR5cCI6IkpXVCJ9.eyJpZCI6MTIzNCwiYW1vdW50Ijo1MDAwLCJpYXQiOjE1NzQyODgyMzZ9.OtY7liEsyPJF-a-i-M5HXmA2IpA4jfUom-E7QIo3usN14JKMvRY5PLhtg0gzcOdGmXZas34bI3tFi0LnQggea77hAFDqsATsBVUUIeb1vnKOpCn8g9kl6F0kn-RYnqGraAUxykULnHArv2L8tly7_8cw2eWo_gHUm_IQPRaByGWyNhBHWJHWgbo7y47w6MylANocxz8Jon14rdZ3z-gX_oftShE27XOQ6EHieQ7xHen7Fw56gILH_5BuXmxBEZ80OYUezah7WAC5LpoKHtxIsU7eGsbWQVaAfw2kwImoPQ-gXrkqDd-unJ5eqZ8VUxT2TJMe-LCU12jRsG7opnJnPKU3RyRg3h_9ARnNVfe6KnmnAYeR4e-yHLlEGp3iN81awmujzKw9a5sZ1L4-0yxbmiWnKQ5sNybXAV5O3BHvbMoV0BE3t4EYlLiOzOY9fMCtQuISRvTx0XxKYZlTq_kL40fcprEOOxhQqkH0DQqq3LtD02nrZxnWcQZ5JrQkVbf5YNRUkZ7mbTN4VamBmwsoZBnjQmSmcNhfACmzkLv48uh8vVMj9Fh6VLduAbcKAo3M1P28ja5lYCm3GDtUdmWItyUu4wMFqdqIwM8_RcsVeeqa_pg2imBpPBHpcQtNS-RDCbjTcvr_pX3VuGjGSDFvPsXSgwfFBnXLuD3U8hKiEQE"
POST Method
Example:
curl --location --request POST 'https://api-dot-zippy-dev-payments.rj.r.appspot.com/payOut' \
--header 'authorization: Bearer token' \
--header 'Content-Type: application/json' \
--data-raw '{
"merchantId": "2021merchant-8Z3D",
"transactionId": "Tx2fA3gX3dTa5vA9iLk",
"country": "PE",
"currency": "PEN",
"typeDocumentId": "1",
"documentId": "75741239",
"amount": "9.00",
"bankId": "Banco de la Nación",
"email": "john.doe@gmail.com",
"typeAccountId": "Cuenta Corriente",
"phone_number": "+51987654321",
"numAccount": "43453430502003513463",
"timestamp": "1610998198",
"name": John Doe,
"payoutMethod": "bankTransfer"
}'
| Parameter | Description | Type | example: the possible domain of required field |
|---|---|---|---|
| merchantId | Unique code assigned to your merchant. | string | 2021merchant-8Z3D |
| transactionId | Unique identifier for the payout request. | string | Tx2fA3gX3dTa5vA9iLk |
| country | Country code where the payout will be processed (ISO 3166-1 alpha-2). | string | PE. |
| currency | Currency code (ISO 4217). | string | PEN. |
| typeDocumentId | Type of identification document of the beneficiary. | string | 1 |
| documentId | National identification number of the beneficiary. | string | 75741239 |
| amount | Amount to be credited to the beneficiary’s account. Must be a string with two decimal places. | string | 9.00 |
| bankId | Identifier of the beneficiary’s bank. | string | Banco de la Nación |
| Beneficiary’s email address. | string | john.doe@gmail.com | |
| typeAccountId | Bank account type of the beneficiary. | string | Cuenta Corriente |
| phone_number | Beneficiary’s mobile phone number (use international format. | string | +51987654321 |
| numAccount | Bank account number of the beneficiary. | string | 43453430502003513463 |
| timestamp | Date in timestamp format. | string | 1610998198 |
| name | Beneficiary’s full name. | string | John Doe. |
| payoutMethod | Withdrawal method to use. If not specified, the request will be processed as a bankTransfer by default. | string | bankTransfer |
Response Parameters
Example Case Ok
{
"status":"in process",
"transactionId": "0011234AB",
"zippyId": "BKY3UlAef0s31yCLmqt4"
}
| Parameter | Description |
|---|---|
| status | Indicates the result of the request. Possible values: "in process" or "error" |
| transactionId | Unique identifier for the payout request. |
| zippyId | Unique identifier assigned by Zippy to the transaction |
| description | Returned only if status = "error". Provides details about the error. |
Example Case Error
{
"status":"error",
"transactionId": "0011234AB",
"description": "Invalid bank account number"
}
Callback
After our system completes the payout to the customer, a callback will be sent to the merchant’s REST API. This callback includes an MD5 signature generated using a predefined format for validation purposes.
| Parameter | Description |
|---|---|
| AMOUNT | Amount of the payout request. The value is a string containing two decimal places. |
| MERCHANTREQUESTID | Internal request ID from your system (same as transactionId used when initiating the payout request). |
| CODE | Status code of the operation: 0 = Validated, 12 = Error. |
| MESSAGE | Message that shows if the transaction was successful or failed. |
| SIGN | MD5 signature generated using the format: MERCHANTREQUESTID + AMOUNT + CODE + key_callback. |
| ZIPPYID | Internal transaction identifier assigned by Zippy. |
Errors
The Zippy API uses the following error codes:
| Error Code | Meaning |
|---|---|
| 400 | Bad Request -- Your request is invalid. |
| 401 | Unauthorized -- Your merchan ID is wrong or invalid. |
| 403 | Forbidden -- The request is hidden for administrators only. |
| 404 | Not Found -- The specified request could not be found. |
| 405 | Method Not Allowed -- You tried to access with an invalid method. |
| 410 | Gone -- The request has been removed from our servers. |
| 429 | Too Many Requests -- You're requesting too many! Slow down! |
| 500 | Internal Server Error -- We had a problem with our server. Try again later. |
| 503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |
Possible errors during payin creation:
| Error Code | Message |
|---|---|
| 400 | field {field_name} is required |
| 400 | {field_name} field wrong |
| 400 | empty field - {field_name} |
| 400 | country field wrong - admissible field: AR - BR - CL |
| 400 | payMethod field wrong - admissible field: bankCard - bankTransfer |
| 400 | field example of amount: 1005.00 |
| 400 | Error: the {email_value} address is incorrect |
| 500 | retry request later |
Possible errors during payout creation:
| Error Code | Message |
|---|---|
| 400 | field {field_name} is required |
| 400 | {field_name} field wrong |
| 400 | empty field - {field_name} |
| 400 | retry request later |
| 400 | invalid payoutMethod for {country_value}. Available methods: wallet, bankTransfer |
| 401 | retry later |
| 401 | The payout JWT or Data is trying to be manipulated |
| 401 | invalid signature |
| 403 | field example of amount: 1005.00 |
| 403 | requires a new transactionId for this payOut |
| 403 | RUT is invalid |
| 403 | DocumentId Blocked |
| 403 | payment methods blocked |