Skip to main content

Payretailers

Introduction​

Payretailers is a service where the users receive a payment reference that allows them to make a payment using PSE, EFECTY and PAGO_FACIL. It also accepts pay-outs. It can be used both in the Paylands checkout and redirection method.

Restrictions and requirements​

Currently only the following currencies are supported: USD, ARS, COP, PEN.

Extra data required​

When generating the payment order, these fields must be provided for checkout and redirection payments:

  • Profile: first_name, last_name, email, document_identification_number, phone
  • Billing_address: city, country, zip_code, address1

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": "Castellon",
        "country": "COL",
        "address1": "Avinguda del Mar 23",
        "zip_code": "12000",
        "state_code": "CT"
    }
}

PSE and Efecty​

Both PSE and EFECTY alternative payment methods (apm) are available using Paylands' checkout and redirection methods. Both methods are only accepted in Colombia and using Colombian pesos or USD.

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": "Castellon",
        "country": "COL",
        "address1": "Avinguda del Mar 23",
        "zip_code": "12000",
        "state_code": "CT"
    }
}

Pago Fácil​

This payment method is also available using Paylands' checkout and redirection method. This method is only available in Argentina and using Argentinean pesos or USD currency.

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": "Castellon",
        "country": "ARG",
        "address1": "Avinguda del Mar 23",
        "zip_code": "12000",
        "state_code": "CT"
    }
}

Khipu payment​

To make a payment with Khipu apm, we can opt for two flows, both redirection and checkout. This method is only accepted in Argentina and Peru, so the country must be ['ARG', 'PER'] and using the currency of Argentine pesos (ARS), Peruvian soles (PEN) or USD. Currently in our sandbox environment, it can only be tested for Peru.

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": "Castellon",
        "country": "PE",
        "address1": "Avinguda del Mar 23",
        "zip_code": "12000",
        "state_code": "CT"
    }
}

Payouts with Payretailers​

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

  • Brazil
  • Mexico
  • Argentina
  • Chile
  • Colombia
  • Peru
  • Ecuador

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
  • 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_typeBRCOCLPEEC
CHECKING✓✓✓✓✓
SAVINGS✓✓✓✓✓
RUT✓

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

  • Argentina: CBU or CVU
  • Mexico: General type

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 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

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

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.

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