Acepta pagos con Pix

Crear un pago en Brasil con Pix consiste en capturar los datos necesarios del cliente para el pago y enviar 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.

Hay dos formas de integrar este método en tu comercio:

• QR estándar (flujo completo): Para quienes desean usar nuestra interfaz ya construida, en donde se genera y se muestra el QR automáticamente al usuario final. Incluye experiencia visual y seguimiento del estado del pago. Este flujo admite pagos con o sin cuenta bancaria registrada.
• QR Base64: Para quienes necesitan solo el código QR en formato Base64, para integrarlo en su interfaz personalizada. Ideal si tienes tu propio front-end o flujo de usuario, y solo necesitas el QR para mostrarlo en donde prefieras. Este flujo también admite pagos con o sin cuenta bancaria registrada.

¿Cómo funciona?

Pix es un sistema de pagos instantáneos, creado y administrado por el Banco Central de Brasil, mediante el cual puedes realizar transacciones en tiempo real mediante códigos QR. Para completar una transacción con este método de pago, el cliente debe tener una cuenta bancaria o de una institución financiera en Brasil, registrarse en el sistema Pix y aprobar la transacción desde su aplicación.

El proceso de pago con Pix consta de cinco etapas principales:

1. Selección de método. El cliente elige pagar con Pix en tu sitio web o aplicación.
2. Generación de QR. ProntoPaga le entrega un QR y un código único al cliente. Este código tiene una duración de 30 minutos para usarse, de lo contrario, pasará a expirado.
3. Pago en aplicación. El cliente podrá escanear el QR con la aplicación de su banco,wallet o ingresar directamente el código único en su aplicación o banca en línea. El cliente realiza el pago siguiendo las instrucciones en pantalla.
4. Captura. El dinero se mueve desde la cuenta del cliente hacia la cuenta de tu comercio.
5. Confirmación. El cliente recibe una confirmación de pago exitoso en su correo electrónico. A su vez, tu comercio recibe la confirmación del pago a través de los webhooks que hayas configurado.

Requisitos regulatorios para comercios gambling

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

Consultar cuentas registradas

Puedes enviar una solicitud de pago con cuenta bancaria registrada o sin cuenta bancaria registrada. Para consultar si un usuario tiene o no cuentas bancarias registradas en Brasil debes enviar una solicitud a este endpoint con el taxId del cliente.

Términos y condiciones

Podrás hacer uso de este endpoint de consulta siempre y cuando el usuario final haya aceptado los términos y condiciones de la Política de Privacidade e Proteção de Dados de ProntoPaga. Del mismo modo, deberás elaborar tus propios términos y condiciones y notificarlos a tu usuario.

Además, ten en cuenta que:

• En la confirmación de pago de una transacción exitosa se resguarda la información bancaria del usuario para futuras transacciones.
• Si tu comercio ya cuenta con la información bancaria del cliente, puedes mandarla en la solicitud de pago.
• El objetivo de enviar la solicitud de pago con información bancaria registrada es lograr transacciones inmediatas y validadas.
• Si el taxId no tiene una cuenta bancaria asociada; el usuario podrá continuar con el pago sin cuenta registrada.
• Si tu comercio es de tipo gambling, puedes mapear hasta tres cuentas bancarias por usuario. Si es un e-commerce, puedes ver todas las cuentas disponibles del usuario.
• Si un usuario ya tiene tres cuentas bancarias mapeadas, no podrá usar la opción de pago sin cuenta registrada.

📘

taxId

Corresponde al número de identificación de la persona física o jurídica.

👍

Cuentas

Si un usuario ya tiene tres cuentas bancarias mapeadas, no podrá usar la opción de pago sin cuenta registrada.

Respuesta exitosa

Si el taxId tiene una o más cuentas bancarias asociadas, recibirás una respuesta similar a esta:

{
  "status": "success",
  "taxId": "123.456.789-01",
  "accounts": [
    {
      "account_number": "123456789012",
      "account_number_full": "123456789012",
      "account_type": "PAYMENT",
      "currency": "BRL",
      "is_active": true,
      "is_default": true,
      "bank": {
        "name": "name of the bank",
        "code": "12345678",
        "country_code": "BR",
        "branch_code": "0001"
      }
    }
  ]
}

Crear un nuevo pago

Tu front-end será el encargado de recopilar los datos necesarios de tu cliente para procesar el pago, mientras que tu back-end se integrará con nuestra API para procesarlo.

De este modo, para crear una solicitud de nuevo pago deberás usar este endpoint y colocar el valor br_pix_payment como método de pago en el body de la solicitud.

Te mostraremos dos formas de enviar la solicitud: una con código QR estándar que muestra una interfaz lista para usarse y otra con un código QR Base64 que puedes renderizar en tu front-end. En ambas formas se puede enviar la solicitud con o sin cuenta bancaria registrada.

La solicitud se envía con tu Bearer Token, así como con tu secretKey. Además, debes incluir los datos necesarios del cliente para hacer el pago, como nombre, correo electrónico, teléfono, país, moneda, monto, entre otros.

También deberás incluir la URL de retorno en caso de que la transacción sea exitosa, así como una URL en caso de que el pago sea rechazado.

QR estándar (flujo completo)

Si buscas una integración práctica y eficiente, contamos con una interfaz lista para usar, que genera y muestra automáticamente el código QR al usuario final. Esta solución ofrece una experiencia visual atractiva; además, te permite monitorear en tiempo real el estado del pago, facilitando una implementación rápida sin comprometer la calidad ni la experiencia del usuario.

Body de la solicitud

A continuación, te mostramos ejemplos de body para la creación de pagos con o sin cuenta bancaria con QR estándar.

QR estándar - Cuenta registrada

A continuación, puedes ver un ejemplo del body que se envía en la solicitud para pagos con cuenta bancaria registrada con QR estándar (flujo completo).

{
  "currency": "BRL",
  "country": "BR",
  "amount": "150.90",
  "clientName": "John Doe",
  "clientEmail": "[email protected]",
  "clientDocument": "12345678901",
  "clientPhone": "999999999",
  "paymentMethod": "br_pix_payment",
  "urlConfirmation": "https://www.webhook.com/confirmation",
  "urlFinal": "https://www.webhook.com/successful",
  "urlRejected": "https://www.webhook.com/rejected",
  "order": "XYZ789",
  "addressLine1": "Rua Haddock Lobo, 50",
  "codePostal": "01234-005",
  "city": "São Paulo",
  "bankCode": "30980539",
  "branchCode": "0001",
  "accountType": "payment",
  "accountNumber": "100000284277",
  "sign": "Signature of the parameters"
}

📘

accountNumber

El parámetro accountNumber soporta entre 7 y 30 caracteres.

QR estándar - Sin cuenta registrada

A continuación, puedes ver un ejemplo del body que se envía en la solicitud para pagos sin cuenta bancaria registrada con QR estándar (flujo completo).

{
  "currency": "BRL",
  "country": "BR",
  "amount": "150.90",
  "clientName": "John Doe",
  "clientEmail": "[email protected]",
  "clientDocument": "12345678901",
  "clientPhone": "999999999",
  "paymentMethod": "br_pix_payment",
  "urlConfirmation": "https://www.webhook.com/confirmation",
  "urlFinal": "https://www.webhook.com/final",
  "urlRejected": "https://www.webhook.com/rejected",
  "order": "XYZ789",
  "sign": "Signature of the parameters"
}

QR Base64

En esta modalidad, al hacer una solicitud de pago y mandar dentro del parámetro theme el valor "{\"type\":\"qr\"}", recibirás en la respuesta de la solicitud el código QR, que podrás renderizar en tu front-end presentarlo directamente en tu página web o aplicación.

Body de la solicitud

A continuación, te mostramos ejemplos de body para la creación de pagos con o sin cuenta bancaria con QR Base64.

📘

Parámetro theme

El campo theme:"{\"type\":\"qr\"}"es obligatorio para crear pagos con QR en Base64.

QR Base64 - Cuenta registrada

A continuación, puedes ver un ejemplo del body que se envía en la solicitud para pagos con cuenta bancaria registrada con QR Base64.

{
  "currency": "BRL",
  "country": "BR",
  "amount": "150.90",
  "clientName": "John Doe",
  "clientEmail": "[email protected]",
  "clientDocument": "12345678901",
  "clientPhone": "999999999",
  "paymentMethod": "br_pix_payment",
  "urlConfirmation": "https://www.webhook.com/confirmation",
  "urlFinal": "https://www.webhook.com/final",
  "urlRejected": "https://www.webhook.com/rejected",
  "order": "XYZ789",
  "addressLine1": "Rua Haddock Lobo, 50",
  "codePostal": "01234-005",
  "city": "São Paulo",
  "bankCode": "30980539",
  "branchCode": "0001",
  "accountType": "payment",
  "accountNumber": "100000284277",
  "theme": "{\"type\":\"qr\"}",
  "sign": "Signature of the parameters"
}

QR Base64 - Sin cuenta registrada

A continuación, puedes ver un ejemplo del body que se envía en la solicitud para pagos sin cuenta bancaria registrada con QR Base64.

{
  "currency": "BRL",
  "country": "BR",
  "amount": "150.90",
  "clientName": "John Doe",
  "clientEmail": "[email protected]",
  "clientDocument": "12345678901",
  "clientPhone": "999999999",
  "paymentMethod": "br_pix_payment",
  "urlConfirmation": "https://www.webhook.com/confirmation",
  "urlFinal": "https://www.webhook.com/final",
  "urlRejected": "https://www.webhook.com/rejected",
  "order": "XYZ789",
  "theme": "{\"type\":\"qr\"}",
  "sign": "Signature of the parameters"
}

Tipos de cuentas

Estos son los posibles tipos de cuentas que se pueden enviar en el parámetro accountType del body request:

• payment
• checking
• salary
• savings

📘

Ten en cuenta que

El parámetro accountType es necesario para pagos con cuentas bancarias registradas.

Códigos bancarios

Para crear pagos con cuenta bancaria registrada, debes enviar el código bancario en el parámetro bankCode. Puedes consultar todos los bancos disponibles y sus valores` en nuestra guía.

Reglas de validación

A continuación, te mostramos las reglas que debes tener en cuenta para los valores en el body de la solicitud.

Respuestas

Como respuesta a una solicitud de pago exitosa, recibirás un enlace para procesar el pago, así como un identificador de pago del sistema.

• Para pagos con QR estándar, recibirás una URL que contiene el código QR plano que muestra el flujo completo de la interfaz.
• Para pagos con QR Base64, también recibirás un código QR plano, además de un código QR en Base64 que puedes renderizar en tu propia interfaz.

Ejemplo de respuesta para QR estándar

{
"uid": "01KKRERAMVGTD7EGX37BZECD30",
"reference": "12345678901234",
"urlPay": "Link to redirect or Iframe to insert"
}

Ejemplo de respuesta para QR Base64

{
"uid": "ID in our services",
"reference": "Reference in our services",
"urlPay": "Link to redirect or Iframe to insert",
"height": "650px",
 "qr": {
   "code": "1234ABCD",
   "codeBase64": "data:image/png;base64,code"
 }
}

Ejemplo de respuesta de pago rechazado

{ 
   "uid": "ID in our services",
   "status": "rejected",
   "reference": "Reason for rejection" 
}

Confirmación de un pago

Una vez que el usuario haya completado el proceso de pago en el formulario, ProntoPaga le mostrará una ventana con el resultado final de su transacción. Al mismo tiempo, devolverá los datos de la transacción a la URL que especificaste en urlConfirmation.

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 pago en el siguiente enlace: Estados de los PayIns.

Devolver un pago

Para solicitar la devolución de un pago exitoso realizado con este método, usa este endpoint. A continuación, se muestra un ejemplo del body request que debe llevar:

{
  "reference": "1111111111",
  "clientDocument": "123.456.789-12",
  "amount": "150.90",
  "urlCallbackRefund": "https://www.webhook.com",
  "sign": "Signature of the parameters"
}

❗️

Estado

Para hacer una devolución el estado del pago debe ser success y el monto debe ser el mismo de la transacción.

👍

Plazos

Las devoluciones tienen un plazo de hasta 3 días para hacerse efectivas.

Ver detalles de un pago

Si así lo deseas, puedes consultar este endpoint con el uid de la transacción para conocer los detalles del pago. Si tu consulta es exitosa, obtendrás una respuesta similar a la siguiente:

{ 
  "uid": [string] // Transaction Identifier 
  "status": [string] // Transaction status 
  "amount": [string] // Transaction amount 
  "method": [string] // Payment method used 
  "reference": [string] // Reference of the transaction 
  "clientEmail": [string] // Client's email address 
  "clientDocument": [string] // Customer's ID number 
  "order": [string] // Payment identifier to be associated with 
  "currency": [string] // ISO currency code 
  "country": [string] // International Country Format 
  "method_type": [string] // Method type 
  "method_detail": [string] // Method details 
  "hash": [string] // Security hash parameter 
  "sign": [string] // Signature of the parameters
}

Tipos de rechazos

La siguiente tabla muestra los tipos de rechazo que pueden derivarse de pagos 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, 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: