Retiros instántaneos con Pix

Hacer un retiro en Brasil por medio de Pix consiste en capturar los datos necesarios de la persona que recibirá el pago y realizar una solicitud a través de nuestra API con un Bearer Token y una secretKey. De esta forma, las transacciones se autentican y se realizan de forma segura.

¿Cómo funciona?

Pix es un sistema de pagos instantáneos, creado y administrado por el Banco Central de Brasil, que permite realizar transacciones en tiempo real mediante códigos QR, claves Pix o transferencias directas. Para completar una transacción con este método de retiro, el cliente debe tener una cuenta bancaria o de una institución financiera en Brasil y registrarse en el sistema Pix.

El proceso de PayOut con QR/Wallet Pix consta de cinco etapas principales:

1. Selección de método. El cliente elige retirar dinero con Pix en tu sitio web o aplicación.
2. Ingreso de datos. El cliente ingresa los datos necesarios para realizar el retiro y confirma la transacción.
3. Validación de datos. ProntoPaga valida la información e inicia la solicitud del retiro.
4. Captura. Se aprueba el retiro y el dinero se mueve desde la cuenta del comercio hacia la cuenta del cliente.
5. Confirmación. Tu comercio recibe la confirmación de retiro exitoso a través de los webhooks que hayas configurado.

Requisitos regulatorios

Debido a la regulación brasileña para comercios de tipo gambling, se incluye una validación de pago a terceros mediante el cual se verifica que la información de la cuenta bancaria del usuario pertenezca al mismo titular del CPF (Cadastro de Pessoa Física). Para ello, ProntoPaga te permite mapear hasta tres cuentas bancarias por usuario.

📘

E-commerce

Para comercios e-commerce, no se aplican restricciones relacionadas con pagos a terceros ni límites en la consulta de cuentas bancarias.

Crea un nuevo retiro

Para hacer una solicitud de nuevo retiro a través de nuestra API deberás usar este endpoint. La solicitud se envía con tu Bearer Token, así como con tu secretKey.

Además, debes incluir los datos necesarios del cliente, como nombre, apellido, correo electrónico, teléfono, ID, cuenta, entre otros.

Body de la solicitud

A continuación puedes ver un ejemplo del body que se envía en la solicitud:

{
    "amount": "150.90",
    "document_id":"123.456.789-12",
    "beneficiaryName": "John",
    "beneficiaryLastName":"Doe",
    "beneficiaryEmail": "[email protected]",
    "beneficiaryPhone" : "55999999999",
    "accountType" :"SL",
    "bankCode" : "001",
    "data": "XYZ789",
    "confirmationURL": "https://www.webhook.com",
    "currency": "BRL",
    "country": "BR",
    "pagamentoType": "1",
    "Type": "payment",
    "accountNumber" :"11111111",
    "agency": "0001",
    "ispb":'30880529',
    "sign": "Signature of the parameters"
}

Respuesta

Como respuesta a una solicitud de pago exitosa, recibirás un identificador del retiro en el sistema (uid), el estado del retiro y los datos adicionales de la transacción.

Ejemplo de respuesta exitosa

{
    "uid": "01KCQ208BJ2VK463NMS1Z6CYAT",
    "status": "new",
    "data": "1675967931",
    "reference": 15503
}

Ejemplo de respuesta fallida

{
  "error": {
    "accountNumber": "(string) accountNumber, cannot be null and account number must be valid."
  }
}

Confirmación de un retiro

Una vez que hayas completado el proceso, ProntoPaga devolverá los datos de la transacción a la URL que especificaste en confirmationURL.

Para confirmar si una transacción fue exitosa, debes verificar que en tu webhook el valor del campo status sea success.

Conoce todos los estados posibles de un retiro en el siguiente enlace: Estados de los PayOuts.

Códigos bancarios

Para retiros con cuenta bancaria registrada, el campo bankCode debe enviarse en la solicitud de creación del retiro, ya que permite identificar la institución financiera del cliente. ProntoPaga procesa transacciones con los principales bancos brasileños.

Revisa el listado completo de códigos bancarios en nuestra guía.

Tipos de rechazos

La siguiente tabla muestra los códigos de rechazo, junto a su descripción, asociados a retiros con Pix en Brasil.

Prueba tu integración

Contamos con un catálogo de datos de prueba que puedes usar para comprobar que tu integración está lista, así como para ver el flujo de pago que seguirá tu cliente. Además, también puedes hacer pruebas con nuestros demos.

Certifica tu integración

La certificación de la integración en sandbox es un paso obligatorio que todos los comercios deben realizar antes de recibir sus credenciales de producción. Su propósito es asegurar que la integración cumpla con los estándares técnicos, funcionales y de seguridad requeridos por ProntoPaga. Dentro de esta sección, se establecen los requisitos que deben cumplirse sin excepción para que la certificación sea aprobada.

Requisitos de certificación

A continuación, encontrarás los distintos requisitos necesarios para completar tu certificación: