Skip to main content

Payretailers

PayRetailers Integration​

PayRetailers allows processing pay-ins through local payment methods in LATAM (PSE, EFECTY, Pago Fácil, Khipu, SPEI, PIX, Transfer, and Colombia Card), as well as pay-outs. Payments can be made via checkout or redirection.

Payins with PayRetailers​

General Requirements​

Supported Currencies​

PayRetailers currently supports the following currencies:

  • USD
  • ARS
  • COP
  • PEN
  • MEX
  • BRL

Required Data (extra_data)​

All payment methods require the following information inside extra_data:

  • profile

    • first_name
    • last_name
    • email
    • document_identification_number
    • phone.number, phone.prefix (if applicable)

  • billing_address

    • city, country, zip_code, address1, state_code

Example:

"extra_data": {
    "checkout": {
        "uuid": "C42043F9-B77C-4918-BD43-86C526B4F24D"
    },
    "profile": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "johndoe@gmail.com",
        "document_identification_number": "92309089",
        "phone": {
            "number": "02614235138",
            "prefix": "54"
        }
    },
    "billing_address": {
        "city": "Bogota",
        "country": "COL",
        "address1": "Calle Mayor, 23",
        "zip_code": "111611",
        "state_code": ""
    }
}

Additional URL Parameters​

ParameterDescriptionExamples
apmSelects the payment method?apm=PSE, ?apm=PIX, ?apm=TRANSFER
langLanguage of the flow?lang=es, ?lang=en, ?lang=pt

Default language: es (Spanish).


Sandbox Environment Behavior​

The sandbox environment of PayRetailers may not fully reflect the real behavior of payment methods.

To simulate final states in sandbox, you can use the following amount values:

amountStatusDescription
11111PaidPayment accepted
44444RefusedPayment cancelled
55555RefusedPayment expired
66666RefusedPayment failed
Any other valueWaiting processor responsePending payment

Payment Methods​

PSE (Colombia)​

  • Country: COL
  • Currencies: COP, USD
  • APM: PSE
"extra_data": {
    "profile": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "test@example.com",
        "document_identification_number": "92309089",
        "phone": { "number": "02614235138", "prefix": "54" }
    },
    "billing_address": {
        "city": "Bogota",
        "country": "COL",
        "address1": "Calle 12",
        "zip_code": "111611",
        "state_code": ""
    }
}

EFECTY (Colombia)​

  • Country: COL
  • Currencies: COP, USD
  • APM: EFECTY

(Same example as PSE)

Pago Fácil (Argentina)​

  • Country: ARG
  • Currencies: ARS, USD
  • APM: PAGO_FACIL
"extra_data": {
    "profile": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "test@example.com",
        "document_identification_number": "92309089"
    },
    "billing_address": {
        "city": "Buenos Aires",
        "country": "ARG",
        "address1": "Av. Libertador 123",
        "zip_code": "1000",
        "state_code": ""
    }
}

Khipu (Argentina and Peru)​

  • Countries: ARG, PER
  • Currencies: ARS, PEN, USD
  • APM: KHIPU
"extra_data": {
    "profile": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "test@example.com",
        "document_identification_number": "92309089"
    },
    "billing_address": {
        "city": "Lima",
        "country": "PER",
        "address1": "Av. Arequipa 123",
        "zip_code": "15046",
        "state_code": ""
    }
}

SPEI (Mexico)​

  • Country: MEX
  • Currencies: MEX, USD
  • APM: SPEI
"extra_data": {
    "profile": {
        "first_name": "Jhon",
        "last_name": "Doe",
        "email": "test@payretailers.com",
        "document_identification_number": "PERM850515MDFPRD32"
    },
    "billing_address": {
        "city": "Ciudad de Mexico",
        "country": "MEX",
        "address1": "Calle Mayor 12",
        "zip_code": "06010",
        "state_code": ""
    }
}

PIX (Brazil)​

  • Country: BRA
  • Currencies: BRL, USD
  • APM: PIX
"extra_data": {
    "profile": {
        "first_name": "Jhon",
        "last_name": "Doe",
        "email": "test@payretailers.com",
        "document_identification_number": "310.535.927-36"
    },
    "billing_address": {
        "city": "Sao Paulo",
        "country": "BRA",
        "address1": "R. Sao Joaquim, 596",
        "zip_code": "01508001",
        "state_code": ""
    }
}

TRANSFER (Ecuador and Brazil)​

  • Countries: ECU, BRA
  • Currencies: USD, BRL
  • APM: TRANSFER
Supported Banks (payment.bank_name)​
CountryAllowed Values
EcuadorBANCO_PICHINCHA, BANCO_GUAYAQUIL
BrazilSANTANDER_BRASIL
Default Values​

If payment.bank_name is not sent:

  • Ecuador → BANCO_PICHINCHA
  • Brazil → SANTANDER_BRASIL
Example (Ecuador, Banco Guayaquil)​
"extra_data": {
    "profile": {
        "first_name": "Jhon",
        "last_name": "Doe",
        "email": "test@payretailers.com",
        "document_identification_number": "00113562600"
    },
    "billing_address": {
        "city": "Quito",
        "country": "ECU",
        "address1": "Av. Amazonas 123",
        "zip_code": "170102",
        "state_code": ""
    },
    "payment": {
        "bank_name": "BANCO_GUAYAQUIL"
    }
}

Card (Colombia)​

  • Country: COL
  • Currencies: COP, USD
  • APM: CARD
"extra_data": {
    "profile": {
        "first_name": "Jhon",
        "last_name": "Doe",
        "email": "test@payretailers.com",
        "document_identification_number": "00113562600",
        "phone": { "number": "579999999999" }
    },
    "billing_address": {
        "city": "Bogota",
        "country": "COL",
        "address1": "Calle Mayor 12",
        "zip_code": "111611",
        "state_code": ""
    }
 }

Limits for transactions​

The following table reflects the transaction limits based on business type, user and country:

CountryCash limit per user per dayCash limit per user per monthOnline limit per user per dayOnline limit per user per monthCredit Card limit per user per dayCredit Card limit per user per month
Ecuador2.000 USD30.000 USD35.000 USD80.000 USDNot availableNot available
Perú2.000 USD30.000 USD35.000 USD80.000 USDNot availableNot available
México2.000 USD30.000 USD35.000 USD80.000 USDNot availableNot available
Panamá2.000 USD30.000 USD35.000 USD80.000 USDNot availableNot available
El Salvador2.000 USD30.000 USD35.000 USD80.000 USDNot availableNot available
Nicaragua2.000 USD30.000 USD35.000 USD80.000 USDNo disponibleNot available
Costa Rica2.000 USD30.000 USD35.000 USD80.000 USD2.500 USD7.000 USD
Chile2.000 USD30.000 USD35.000 USD80.000 USD35.000 USD80.000 USD
Brazil10.000 USD30.000 USD35.000 USD80.000 USDNot availableNot available
Guatemala2.000 USD8.000 USDNot availableNot availableNot availableNot available
Colombia10.000 USD30.000 USD35.000 USD80.000 USD2.500 USD7.000 USD
Argentina10.000 USD30.000 USD35.000 USD80.000 USD2.500 USD7.000 USD

Transaction errors​

With this table we reflect possible errors that may arise in the payment process:

Error MessageMeaning
PAYMENT_METHOD_NOT_ALLOWEDThe payment method ID used in the request is not active or enabled, and cannot be used.
PAYMENT_PSP_ERRORGeneric error message received from the PSP, normally originated from a timeout on the PSP side in high traffic instances.
PERSONAL_ID_VALIDATION_FAILEDThe PersonalID doesn't exist or belongs to a minor, deceased individuals or PEP and associates. Also the payment will be blocked if the PersonalID is related to any international lists of money laundering and/or terrorist financing.
TRANSACTION_INVALID_FIELD_LANGUAGEThe "Language" field of the request contains an invalid language value.
TRANSACTION_INVALID_FIELD_CURRENCYThe "Currency" field contains an unsupported or invalid currency value.
TRANSACTION_INVALID_FIELD_COUNTRYThe "Country" field contains an unsupported or invalid country value.
TRANSACTION_INVALID_EMAILThe "Email" field contains an invalid value(normally due to email syntax).
TRANSACTION_INVALID_CPF(Brazil only) the "personalID" field contains an invalid value.
TRANSACTION_MIN_AMOUNTThe “Amount” field contains a value that is below the minimum limit for the requested payment method.
TRANSACTION_MAX_AMOUNTThe “Amount” field contains a value that exceeds the maximum limit for the requested payment method.
INVALID_AMOUNTThe value sent for “amount” is not an integer.
TRANSACTION_REQUIRED_COUNTRYThe "Country" parameter is empty.
TRANSACTION_REQUIRED_CURRENCYThe "Currency" parameter is empty.
TRANSACTION_BLOCKED BY_CUSTOMER_LIMIT_RULEThe daily/monthly limit of transaction attempts for this customer has been reached, and no transactions can be generated for the customer until the next day/week/month.
CUSTOMER_COMPLIANCE_VALIDATION_FAILED(Brazil only) the "personalID" field contains a non-existent CPF.
MERCHANT_COMPLIANCE VALIDATION_ERRORIf one of your users is blocked with this error message please expose your case on our Freshdesk.
PAYMENT_PSP_ERRORGeneric error message received from the payment partner PSP, usually comes from a timeout on PSP’s side in high traffic instances.
TRANSACTION_CREATION_ERRORThe payment method used in the request is not active and cannot be used. Shop credentials have been disabled.
PAYMENT_AMOUNT_NOT_EQUALThe paid amount differs from the original amount or QR amount.
PAYER_CPF_NOT_EQUALThe payer's document number(CPF) does not match the buyer's document number.
CORPORATE_BANK_ACCOUNT_PAYMENT_NOT_ALLOWEDThe transaction was paid from a corporate bank account.
PAYMENT_COMPLIANCE_VALIDATION_FAILEDThe transaction was paid from a corporate bank account.
CUSTOMER_INVALID_AGEUnderaged.
CUSTOMER_INVALID_AGE_NULLPayer age not available.
CUSTOMER_INVALID_STATUSCPF is not valid/ active (deceased customer).
CUSTOMER_IS_PEPPolitically exposed person.
CUSTOMER_IS_PEP_RELATEDFamily member of a politically exposed person.
CUSTOMER_IS_IN_INTERNATIONAL_LISTSCustomer is in the lavajato/laft list.
CUSTOMER_SUSPENDED_STATUSCPF suspend by government triggered/criminal illegal activities.
CUSTOMER_POSSIBLE_INVALID_STATUSIn process of losing CPF.
CUSTOMER_NOT_FOUNDNo CPF data available.

Payouts with Payretailers​

Payretailers allows payouts (fund transfers) in the following countries:

CountryCurrency
BrasilBRL
MéxicoMXN
ChileCLP
ColombiaCOP
PerúPEN
EcuadorUSD

There are two payout methods:

MethodDescriptionSupported Countries
TransferTraditional bank transferAll of the above
PIXInstant transfer using PIX keyBrazil only

Required fields in extra_data​

profile (always required):​

  • first_name
  • last_name
  • email
  • document_identification_number
  • document_identification_type (optional; only for COL, ECU, and PER. Valid values: NATIONAL_IDENTITY_DOCUMENT, FOREIGN_IDENTIFICATION_DOCUMENT, FISCAL_IDENTIFICATION_CODE, VALID_PASSPORT)
  • phone.number (required only if country is BRA, PER, or ECU)

billing_address:​

  • address1
  • country

payment (depending on payout type):​

If payout type is Transfer:

  • bank_name (except Argentina) – This field must contain the bank code of the recipient. See Bank Codes by Country for valid values.
  • account See specifications
  • account_type (except Argentina and Mexico)
  • account_agency_number (Brazil only, required) – Numeric code of the bank agency, provided by the bank. Use only the digits before the dash (e.g.: "1234-5" → send "1234").
  • aba_swift (optional, Brazil only)
  • payout_beneficiary_type_code (optional, Chile only. Values: PERSON (default), COMPANY)

If payout type is PIX (Brazil only):

  • recipient_pix_key (optional. If not specified, CPF is used as PIX key)

document_identification_type values by country​

This field is included inside profile, is optional, and can only be used for Colombia, Ecuador, and Peru. If not provided, NATIONAL_IDENTITY_DOCUMENT will be used by default. For other countries, do not include this field.

Countrydocument_identification_type ValueEquivalent Document Type
ARGDNI
BRCPF
CLRUT
MXCURP
COLNATIONAL_IDENTITY_DOCUMENTCédula de ciudadanía
COLFOREIGN_IDENTIFICATION_DOCUMENTForeigner ID
ECUNATIONAL_IDENTITY_DOCUMENTDNI
ECUFISCAL_IDENTIFICATION_CODERUC
ECUVALID_PASSPORTPassport
PERNATIONAL_IDENTITY_DOCUMENTDNI
PERFOREIGN_IDENTIFICATION_DOCUMENTForeigner card
PERFISCAL_IDENTIFICATION_CODERUC
PERVALID_PASSPORTPassport

account_type values by country (Transfer)​

account_typeBRCOCLPEECMX
CHECKING✓✓✓✓✓
SAVINGS✓✓✓✓✓
RUT✓
ACCOUNT_CLABE✓
CARD_NUMBER✓

Argentina and Mexico do not require account_type; a default internal value is used:

  • Argentina: CBU or CVU
  • Mexico: General type (ACCOUNT_CLABE)

Specifications for account by country (Transfer)​

Expected length / format​

Data validation: ^[0-9]+$ (only digits allowed in account)

CountryExpected lengthAdditional comments
AR (Argentina)22CBU or CVU
BR (Brazil)13—
CL (Chile)16—
CO (Colombia)16—
MX (Mexico)16, 18General (ACCOUNT_CLABE): 18 digits
Debit card number (CARD_NUMBER): 16 digits
EC (Ecuador)12—
PE (Peru)10, 13, 14, 18, 20Depends on the bank. See details

Details for Peru (account)​
Bank / InstitutionExpected lengthComments / Examples
Banco de Crédito (BCP)13 / 1413 = checking/master.
14 = savings
Interbank13—
Banco Continental (BBVA)18 / 20Ex.:
18: 001106660100012345
20: 00110666010001234512
Scotiabank103 digits branch + 7 digits account.
Ex.: 0037651234
Other banks / FIs20Mandatory CCI.
Ex.: 00219400254640654321

PIX key format (recipient_pix_key)​

Key TypeRegex FormatExample
CPF^[0-9]{11}$12345678901
Phone^+[1-9][0-9]\d{1,14}$+5510998765432
Email^[a-z0-9.!#$&'*+/=?^_{}~-]+@[a-z0-9.-]+$pix@bcb.gov.br
Random[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}123e4567-e89b-12d3-a456-426655440000

Note: If recipient_pix_key is not explicitly provided in extra_data.payment, the value of document_identification_number will automatically be used as PIX key, as long as it's a valid CPF. This simplifies integration in most cases.

Examples of extra_data for payouts of type Transfer​

Ecuador​

"extra_data": {
  "profile": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "jon.doe@test.com",
    "document_identification_number": "00113562600",
    "document_identification_type": "NATIONAL_IDENTITY_DOCUMENT",
    "phone": {
      "number": "572222222222"
    }
  },
  "billing_address": {
    "city": "Quito",
    "country": "ECU",
    "address1": "Portete E19-151",
    "address2": null,
    "address3": null,
    "zip_code": "",
    "state_code": ""
  },
  "payment": {
    "bank_name": "0001",
    "account": "123123123124",
    "account_type": "CHECKING"
  }
}

Brazil​

"extra_data": {
  "profile": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@test.com",
    "document_identification_number": "00113562600",
    "phone": {
      "number": "5511999999999"
    }
  },
  "billing_address": {
    "city": "Sao Paulo",
    "country": "BRA",
    "address1": "R. Sao Joaquim, 596",
    "address2": null,
    "address3": null,
    "zip_code": "",
    "state_code": ""
  },
  "payment": {
    "bank_name": "341",
    "account": "0001",
    "account_type": "CHECKING",
    "account_agency_number": "8585",
    "aba_swift": "ERDSAD"
  }
}

Sandbox Testing​

In the sandbox environment, you can simulate different payout results using the amount value when generating the payment order:

  • Any value other than 666 simulates a successful payout.
  • The value 666 simulates a rejected payout.

Limits for payouts​

The following table reflects the transaction limits based on business type, user and country:

CountryLimit per dayLimit per weekLimit per monthLimit per yearLimit per transaction
Brazil10.000 USD70.000 BRL150.000,00 BRLNo limitNo limit
México5.000 USDNo limit20.000 USDNo limitNo limit
Chile5.000 USDNo limit20.000 USDNo limitNo limit
Colombia5.000 USDNo limit20.000 USDNo limit10.000.000 COP
Perú3.500 USDNo limit7.000 USD84.000 USDNo hay
Ecuador3.500 USDNo limit7.000 USD84.000 USDNo limit

Bank Codes by Country​

You can find the valid values for the payment.bank_name field for each country in the following section. This field must contain a numeric code.

Brazil​

You can view the full list of banks at conta-corrente.com

CodeBank
001Banco do Brasil S.A.
341Banco Itaú S.A.
033Banco Santander (Brasil) S.A.
237Banco Bradesco S.A. / Next
104Caixa Econômica Federal
422Banco Safra S.A.
748Banco Cooperativo Sicredi S.A.
041Banco do Estado do Rio Grande do Sul S.A.
208BANCO BTG PACTUAL S.A.
655Neon Pagamentos
077Banco Inter S.A.
121Banco Agibank S.A.
212Banco Original S.A
260Nubank
336Banco C6 S.A.
413Banco BV (Before Banco Votorantim)

Chile​

CodeBank
012Banco Del Estado De Chile
001Banco De Chile / Banco A. Edwards / Credichile
028Banco Bice
051Banco Falabella
053Banco Ripley
037Banco Santander – Santiago
049Banco Security
014Scotiabank / Sud – Americano
016BCI / Tbanc

Mexico​

CodeBank
40012BBVA Bancomer
40021HSBC
40014Santander
40072Banorte
40127Banco Azteca
40137Bancoppel
40131Banco Famsa
40138ABC Capital
40150Banco Inmobiliario

To view the full list of banks in Mexico, see: Banks in Mexico - PayRetailers

Colombia​

CodeBank
0001Banco de Bogotá
0007Bancolombia
0013BBVA Colombia
0014Itaú
0019Banco Colpatria
0023Banco de Occidente
0051Banco Davivienda S.A.
0052Banco AV Villas
0062Banco Falabella S.A.
0070Lulo Bank
0507Nequi
0801MOVii

Ecuador​

CodeBank
0001Banco Amazonas
0002Banco Bolivariano
0004Banco Central del Ecuador
0010Banco de Guayaquil
0011Banco de la Producción
0016Banco del Pacífico
0023Banco Pichincha
0025Banco Promerica
0026Banco Solidario

Perú​

CodeBank
0001Interbank
0002BBVA Perú
0003BCP Perú
0004Scotiabank Perú
0006Banco Pichincha
0007Mibanco
0008Banco de la Nación
0010Banco Santander
0012Banco Falabella
0013Banco Ripley
0014Banco GNB
0015Banco Azteca
0016Banco Cencosud
0019Caja Arequipa
0025Caja Piura
0027Caja Tacna