Saltar al contenido principal

Payretailers

Introducción​

Payretailers es un servicio donde el usuario recibe una referencia que le permite realizar un pago mediante PSE, EFECTY, PAGO_FACIL. También permite pay-outs. Puede ser utilizado tanto en el checkout de Paylands como mediante redirección.

Restricciones y requisitos​

Actualmente solo soporta las monedas: USD, ARS, COP, PEN.

Datos extra requeridos​

Al generar la orden de pago se deben enviar estos campos para los pagos via checkout y redirección:

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

Ejemplo:

"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 y Efecty​

Para hacer un pago con los apms de PSE y EFECTY, podemos optar por dos flujos, tanto redirección como checkout. Ambos métodos están aceptados únicamente en Colombia, por lo que el country deberá ser 'COL' y usando la moneda de pesos colombianos (COP) o USD.

Ejemplo:

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

Para hacer un pago con el apm de Pago Fácil, podemos optar por dos flujos, tanto redirección como checkout. Este método está aceptado únicamente en Argentina, por lo tanto el country deberá ser 'ARG' y usando la moneda de pesos argentinos (ARS) o USD.

Ejemplo:

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

Pago Khipu​

Para hacer un pago con el apm de Khipu, podemos optar por dos flujos, tanto redirección como checkout. Este método está aceptado únicamente en Argentina y Perú, por lo tanto el country deberá ser ['ARG', 'PER'] y usando la moneda de pesos argentinos (ARS), soles peruanos (PEN) o USD. Actualmente en nuestro entorno sandbox, solo se puede probar para Perú.

Ejemplo:

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

Payouts con Payretailers​

Payretailers permite realizar payouts (envíos de fondos) en los siguientes países:

  • Brasil
  • México
  • Argentina
  • Chile
  • Colombia
  • Perú
  • Ecuador

Existen dos métodos de payout:

MétodoDescripciónPaíses compatibles
TransferTransferencia bancaria tradicionalTodos los anteriores
PIXTransferencia inmediata mediante clave PIXSolo Brasil

Campos obligatorios en extra_data​

profile (siempre requerido):​

  • first_name
  • last_name
  • email
  • document_identification_number
  • document_identification_type (opcional; solo para COL, ECU y PER. Valores posibles: NATIONAL_IDENTITY_DOCUMENT, FOREIGN_IDENTIFICATION_DOCUMENT, FISCAL_IDENTIFICATION_CODE, VALID_PASSPORT)
  • phone.number (requerido solo si country es BRA, PER o ECU)

billing_address:​

  • address1
  • country

payment (según el tipo de payout):​

Si el tipo de payout es Transfer:

  • bank_name (excepto Argentina) – Este campo debe contener el código del banco del destinatario. Consulta la sección Códigos de bancos por país para ver los valores válidos según el país.
  • account
  • account_type (excepto Argentina y México)
  • account_agency_number (solo Brasil, obligatorio) – Código numérico de la agencia bancaria, proporcionado por el banco. Usar solo los números antes del guion (ej: "1234-5" → enviar "1234").
  • aba_swift (opcional y solo Brasil)
  • payout_beneficiary_type_code (opcional, solo Chile. Valores: PERSON (por defecto), COMPANY)

Si el tipo de payout es PIX (solo Brasil):

  • recipient_pix_key (opcional. Si no se indica, se usa el CPF como clave PIX)

Valores de document_identification_type por país​

El campo document_identification_type se incluye dentro de profile, es opcional y solo se puede usar para los países Colombia, Ecuador y Perú. Si no se indica, se utilizará por defecto NATIONAL_IDENTITY_DOCUMENT. Para el resto de países, no se debe enviar este campo.

PaísValor document_identification_typeTipo de documento equivalente
ARGDNI
BRCPF
CLRUT
MXCURP
COLNATIONAL_IDENTITY_DOCUMENTCédula de ciudadanía
COLFOREIGN_IDENTIFICATION_DOCUMENTDocumento de extranjero
ECUNATIONAL_IDENTITY_DOCUMENTDNI
ECUFISCAL_IDENTIFICATION_CODERUC
ECUVALID_PASSPORTPasaporte
PERNATIONAL_IDENTITY_DOCUMENTDNI
PERFOREIGN_IDENTIFICATION_DOCUMENTCarnet de extranjería
PERFISCAL_IDENTIFICATION_CODERUC
PERVALID_PASSPORTPasaporte

Valores de account_type por país (Transfer)​

account_typeBRCOCLPEEC
CHECKING✓✓✓✓✓
SAVINGS✓✓✓✓✓
RUT✓

Argentina y México no requieren account_type, se aplica un valor por defecto interno:

  • Argentina: CBU o CVU
  • México: tipo General

Formato de clave PIX (recipient_pix_key)​

Tipo claveFormato regexEjemplo
CPF^[0-9]{11}$12345678901
Teléfono^+[1-9][0-9]\d{1,14}$+5510998765432
Email^[a-z0-9.!#$&'*+/=?^_{}~-]+@[a-z0-9.-]+$pix@bcb.gov.br
Aleatorio[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

Nota: Si no se indica explícitamente el campo recipient_pix_key dentro de extra_data.payment, se utilizará automáticamente el valor del campo document_identification_number como clave PIX, siempre que este represente un CPF válido, simplificando la integración en los casos más comunes.

Ejemplos de extra_data para payouts de tipo 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"
  }
}

Brasil​

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

Pruebas en entorno de sandbox​

En el entorno de sandbox, puedes simular distintos resultados en las operaciones de payout utilizando el valor del campo amount que indicarás al generar la orden de pago:

  • Cualquier valor distinto de 666 simula un payout exitoso.
  • El valor 666 simula un payout rechazado.

Limites para las transacciones

Con esta tabla reflejamos los limites por tipo de comercio, usuario y pais:

PaisLímite de efectivo por usuario y díaLímite de efectivo por usuario y mesLímite en línea por usuario y díaLímite en línea por usuario y mesCredit Card limit per user per dayCredit Card limit per user per month
Ecuador2.000 USD30.000 USD35.000 USD80.000 USDNo disponibleNo disponible
Perú2.000 USD30.000 USD35.000 USD80.000 USDNo disponibleNo disponible
México2.000 USD30.000 USD35.000 USD80.000 USDNo disponibleNo disponible
Panamá2.000 USD30.000 USD35.000 USD80.000 USDNo disponibleNo disponible
El Salvador2.000 USD30.000 USD35.000 USD80.000 USDNo disponibleNo disponible
Nicaragua2.000 USD30.000 USD35.000 USD80.000 USDNo disponibleNo disponible
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
Brasil10.000 USD30.000 USD35.000 USD80.000 USDNo disponibleNo disponible
Guatemala2.000 USD8.000 USDNo disponibleNo disponibleNo disponibleNo disponible
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

Limites para los payouts

Con esta tabla reflejamos los limites por tipo de comercio, usuario y pais:

PaisLímite por díaLímite por semanaLímite por mesLímite por añoLimite por transacción
Brasil10.000 USD70.000 BRL150.000,00 BRLNo hayNo hay
México5.000 USDNo hay20.000 USDNo hayNo hay
Chile5.000 USDNo hay20.000 USDNo hayNo hay
Colombia5.000 USDNo hay20.000 USDNo hay10.000.000 COP
Perú3.500 USDNo hay7.000 USD84.000 USDNo hay
Ecuador3.500 USDNo hay7.000 USD84.000 USDNo hay

Errores de transacciones

Con esta tabla reflejamos posibles errores que puedan surgir en el processo del pago:

Mensaje de errorSignificado
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.

Códigos de bancos por país​

Puedes consultar los valores válidos del campo payment.bank_name para cada país en la siguiente sección. Este valor consisitrá en un código numérico.

Brasil​

Puedes consultar la lista completa de bancos en conta-corrente.com

CódigoBanco
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​

CódigoBanco
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

México​

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

Para ver la lista completa de bancos en México, consulta: Bancos de México - PayRetailers

Colombia​

CódigoBanco
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​

CódigoBanco
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ú​

CódigoBanco
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