Skip to main content
La API de Pix Automático atiende el lado del pagador de los pagos Pix recurrentes. Con ella, el pagador acepta o rechaza una solicitud de autorización, gestiona la autorización y cancela débitos programados.

​
Llama a la API desde tu backend

Quien llama es el backend de tu PSP, autenticado con un token de aplicación. El token identifica tu aplicación, no a uno de tus clientes. Tu backend autentica al pagador y lo autoriza para la cuenta antes de llamar a la API.
  • Envía la cuenta del pagador en X-Account-Id en las operaciones con alcance de cuenta. Crear solicitud de autorización desde un código QR recibe la cuenta en el campo payerAccountId del cuerpo.
  • Un recurso que pertenece a una cuenta distinta de la que envías devuelve 404.
  • Envía X-Idempotency en cada escritura. Reutiliza el valor solo para reintentar la misma solicitud.

​
Inicia una autorización desde un código QR

  1. Llama a Crear solicitud de autorización desde un código QR. Envía el contenido sin procesar del código QR en qrCodePayload y la cuenta del pagador en payerAccountId.
  2. La API decodifica el código QR y detecta el recorrido. Luego resuelve la cuenta del pagador en el CRM y lee el payload de la recurrencia en el PSP receptor por HTTPS.
  3. En el recorrido 3, envía immediatePayment.result como SETTLED. Envía también immediatePayment.settlementConfirmedAt, el momento en que tu institución recibió la confirmación de la liquidación. Sin él, la API no envía una autorización aceptada a BACEN. En el recorrido 4, un resultado FAILED detiene el recorrido.
  4. Conserva el authorizationRequestId de la respuesta. La solicitud espera la decisión del pagador hasta expiresAt.
Si la API no puede leer el payload de la recurrencia, el recorrido se detiene con un error y la API no crea ninguna solicitud. Si el CRM no tiene la cuenta del pagador, la API responde 422 (PIX-0813). Si la API no puede acceder al CRM o no tiene la dirección del CRM, la API responde 503 (PIX-0814). En el recorrido 1, la solicitud viene del PSP receptor. También aparece en la lista de solicitudes pendientes.

​
Decide una solicitud pendiente

  1. Llama a Listar solicitudes de autorización para obtener las solicitudes que esperan la decisión del pagador. Una solicitud sale de esta lista cuando el pagador la acepta o la rechaza, cuando el PSP receptor la cancela o cuando vence.
  2. Llama a Decidir solicitud de autorización con decision definido como ACCEPT o REJECT. Usa exactamente el authorizationRequestId que devolvió la API.
  3. Para aceptar, también puedes enviar los parámetros del pagador. Un parámetro que no envías toma su valor por defecto: notificaciones activadas, línea de crédito activada y ningún importe máximo.
  4. Para rechazar, envía rejectionReason como NotRecognizedByDebtor o RejectedByDebtor.
  5. Llama a Obtener solicitud de autorización para leer el resultado. Devuelve la solicitud en cualquier estado.
La decisión es un único comando. No hay un segundo paso de confirmación. La API envía la decisión al PSP receptor de forma asíncrona. En el recorrido 1, el PSP receptor no responde a un rechazo. En los recorridos 2, 3 y 4, la API registra un rechazo y no lo envía.

​
Gestiona las autorizaciones

  • Listar autorizaciones devuelve las autorizaciones que no terminaron: APPROVED y AWAITING_CONCLUSION. Envía include_terminated=true para obtener también las autorizaciones REJECTED, EXPIRED y CANCELLED.
  • Una autorización AWAITING_CONCLUSION no está activa en el BACEN hasta que el PSP receptor concluye el proceso. Filtra por status=APPROVED para obtener solo las autorizaciones vigentes.
  • Obtener autorización devuelve una autorización en cualquier estado.
  • Listar historial de la autorización devuelve la auditoría de las transiciones de estado. Cada entrada tiene el estado anterior, el estado nuevo, el instante y el actor.

​
Cambia los parámetros del pagador

Actualizar parámetros de la autorización aplica un JSON merge patch (RFC 7386) a los tres parámetros del pagador: maximumAmount, schedulingNotificationsEnabled y creditLineEnabled. Envía el cuerpo como application/merge-patch+json.
  • Omite un parámetro para conservar su valor.
  • Define un parámetro como null para restablecer su valor por defecto. Las dos opciones están activadas por defecto, así que un restablecimiento no las desactiva.
  • Un cambio se aplica a los débitos programados después de él. Un débito que ya está programado conserva el importe máximo vigente cuando se programó.
  • En una autorización creada mediante Open Finance, la API rechaza un cambio de maximumAmount con 409 (PIX-0812). Los otros dos parámetros siguen siendo editables.

​
Cancela una autorización

Cancelar autorización termina la autorización a pedido del pagador. La cancelación es inmediata. También cancela los débitos programados bajo la autorización, incluidos los reintentos después del vencimiento. Los débitos con liquidación prevista para el día de la cancelación siguen programados y se liquidan ese día. La respuesta informa cancelledScheduledPayments y preservedScheduledPayments. Un recuento de preservados mayor que cero es el comportamiento correcto, no una falla parcial. El campo reason es una nota de texto libre para la pista de auditoría del pagador. El PSP receptor recibe el código SLDB, que la respuesta devuelve en counterpartyReason. Cuando el PSP receptor cancela la recurrencia, la API también cancela los débitos programados bajo ella. Conserva los débitos que vencen el día en que llega la cancelación, y los del día siguiente cuando llega a las 22:00 o después, en la zona horaria America/Sao_Paulo. También conserva un débito con un intento de liquidación en cualquier estado distinto de REJECTED.

​
Cancela un débito programado

  1. Llama a Listar pagos programados para obtener el identificador del débito. Esta lista también conserva los débitos cancelados. Un débito liquidado conserva el estado SCHEDULED, y su bloque settlement trae el resultado del pago.
  2. Llama a Cancelar pago programado con ese identificador.
Cancelar un débito no cambia la autorización. La autorización sigue vigente y los próximos débitos siguen programados. Para terminar la autorización, cancela la autorización. La API rechaza la cancelación con 409 en estos casos:
  • La solicitud llega a las 00:00 de la fecha de liquidación o después, en la zona horaria America/Sao_Paulo (PIX-0825).
  • El débito viene de un reintento después del vencimiento, con finalidad NTAG (PIX-0826).
  • El débito ya no está SCHEDULED.
Para las convenciones de solicitud de Pix Lerian, consulta Integración con Pix Lerian.