Ficha técnica
Alcances necesarios
El token para consumir la API de Pix automático debe generarse utilizando el Authorization Code.
Es necesario incluir el siguiente alcance:
| Alcance | Descripción |
|---|---|
| brn:btg:empresas:banking:collections | Permite la consulta y gestión de cobros |
Jornadas del Pix Automático
Esta API soporta las jornadas 1, 2 y 3 del Pix Automático.
Las instrucciones para la utilización de cada una de las jornadas se encontrarán en el endpoint de Crear Autorización de Pix Automático
Especificidades
Autorización con valor variable
Para la emisión de una autorización de pix automático con valor variable, es necesario que el campo amount no sea enviado. De esta manera, el sistema inferirá que no hay un valor fijo.
Eventos de webhook de la Jornada 3
La Jornada 3 del Pix Automático cuenta con dos componentes de pago:
- Pago inmediato de un Pix QR Code.
- Pago de la recurrencia según el intervalo definido a través de la API.
Estos componentes generan eventos DIFERENTES cuando ocurren, siendo estos:
- Para el pago inmediato se genera el evento
instant-collections.paidconforme al Pix cobranza dinámica. Por ello, es necesario otorgar el consentimiento para la API de Pix cobranza dinámica, según lo descrito en Webhooks. - Para el pago de la recurrencia se genera el evento
automatic-pix.scheduling-paid.
Eventos de webhook
Los payloads disponibles a continuación representan el contenido del campo data.
| Evento | Descripción |
|---|---|
automatic-pix.authorization-created | Autorización de pix automático creada. |
automatic-pix.scheduling-approved | Programación de pix automático aprobada. |
automatic-pix.authorization-rejected | Autorización de pix automático rechazada. |
automatic-pix.cancelled | Cancelación en el flujo de pix automático. |
automatic-pix.scheduling-paid | Pago de programación de pix automático. |
automatic-pix.authorization-created
{
"authorizationId": "1a34ece5-8ae1-4659-977e-b5bac829c4eb",
"createdAt": "2025-06-28T01:41:20.901Z",
"initialDate": "2025-07-30",
"link": {
"contract": "270620251040",
"debtor": {
"taxId": "***153188**",
"name": "Nome do Pagador",
"personType": "F"
}
},
"origin": "DEVELOPERS",
"payee": {
"taxId": "00000000000000",
"name": "Nome da Empresa",
"personType": "J",
"account": {
"number": "000000000",
"branchCode": "50",
"status": "PARTIALLY_BLOCKED"
},
"desk": "PME"
},
"period": "MONTHLY",
"requests": [],
"retryPolicy": "ACCEPT_3R_7D",
"status": "CREATED",
"updatedAt": "2025-06-28T01:41:20.901Z",
"useLineOfCredit": true,
"activation": {
"journeyType": "WAITING_DEFINITION",
"txId": "b49adc6480d84eda87b3653cedc2a6fc"
},
"externalId": "36daac06-eaeb-4fe7-8088-c59f38d585be",
"finalDate": "2026-05-30",
"location": {
"locationId": "31231abb-c822-43a6-8bfd-7c13c4d9b359",
"payeeTaxId": "00000000000000",
"typeCob": "REC",
"createdAt": "2025-06-28T01:41:23.008Z",
"externalId": 9082893086585425000,
"externalUrl": "api.developer.btgpactual.com/pc/p/v2/rec/361be04ccc8a48fe95376bfcfb4bdeec",
"path": "00000000000000/31231abb-c822-43a6-8bfd-7c13c4d9b359.png",
"url": "https://static.empresas.btgpactual.com/pix/dynamic/qrcode/00000000000000/31231abb-c822-43a6-8bfd-7c13c4d9b359.png"
},
"minimumAmountPayee": 0.01,
"qrCodeInfo": {
"emv": "00020101021226910014br.gov.bcb.pix2569api.developer.btgpactual.com/pc/p/v2/3***80950014br.gov.bcb.pix2573api.developer.btgpactual.com/pc/p/v2/rec/361be04ccc8a48fe95376bfcfb4bdeec6304C47B",
"journeyType": "JOURNEY_3"
},
"totalInstallments": 10
}
automatic-pix.scheduling-approved
{
"authorizationId": "1a34ece5-8ae1-4659-977e-b5bac829c4eb",
"createdAt": "2025-06-28T01:41:20.901Z",
"initialDate": "2025-07-30",
"link": {
"contract": "270620251040",
"debtor": {
"name": "Nome do Pagador",
"taxId": "***153188**",
"personType": "F"
}
},
"origin": "DEVELOPERS",
"payee": {
"name": "Nome da Empresa",
"taxId": "00000000000000",
"personType": "J",
"account": {
"branchCode": "50",
"number": "000000000"
},
"desk": "PME"
},
"period": "MONTHLY",
"requests": [],
"retryPolicy": "ACCEPT_3R_7D",
"status": "APPROVED",
"updatedAt": "2025-06-28T01:44:29.716Z",
"useLineOfCredit": true,
"activation": {
"journeyType": "JOURNEY_3",
"txId": "b49adc6480d84eda87b3653cedc2a6fc"
},
"approvedAt": "2025-06-28T01:44:29.716Z",
"externalId": "36daac06-eaeb-4fe7-8088-c59f38d585be",
"finalDate": "2026-05-30",
"location": {
"locationId": "31231abb-c822-43a6-8bfd-7c13c4d9b359",
"payeeTaxId": "00000000000000",
"typeCob": "REC",
"createdAt": "2025-06-28T01:41:23.000Z",
"path": "00000000000000/31231abb-c822-43a6-8bfd-7c13c4d9b359.png",
"url": "https://static.empresas.btgpactual.com/pix/dynamic/qrcode/00000000000000/31231abb-c822-43a6-8bfd-7c13c4d9b359.png"
},
"minimumAmountPayee": 0.01,
"payer": {
"taxId": "***153188**",
"personType": "F",
"account": {
"number": "000000000",
"branchCode": "00",
"ispbParticipant": "00000000"
}
},
"qrCodeInfo": {
"journeyType": "JOURNEY_3",
"emv": "00020101021226910014br.gov.bcb.pix2569api.developer.btgpactual.com/pc/p/v2/3***80950014br.gov.bcb.pix2573api.developer.btgpactual.com/pc/p/v2/rec/361be04ccc8a48fe95376bfcfb4bdeec6304C47B"
},
"totalInstallments": 10
}
automatic-pix.authorization-rejected
{
"schedulingId": "88b54f88-0ea5-4e70-bb6c-bcf9ab4a88cc",
"createdAt": "2025-07-17T19:43:24.720Z",
"authorizationId": "2bcccc1f-1d5d-416e-b4d9-f8a9e9955cd4",
"scheduledDate": "2025-07-20",
"installmentNumber": 1,
"payee": {
"name": "PAYEE",
"taxId": "99234527000999",
"personType": "J",
"account": {
"branchCode": "50",
"number": "004909999"
},
"desk": "PME"
},
"payer": {
"personType": "F",
"taxId": "***845326**",
"account": {
"branchCode": "1",
"number": "43456798",
"ispbParticipant": "9876654"
}
},
"status": "REJECTED",
"updatedAt": "2025-07-17T19:44:31.993Z",
"amount": 1.08,
"origin": "DEVELOPERS",
"rejectedAt": "2025-07-17T19:44:31.993Z",
"rejectionDescription": "Expiry date does not match recurrence frequency based on last schedule and/or product rules.",
"rejectionCode": "DTED",
"firstTxId": "1234444dd6a274d6b444c2be5a1d91bdf"
}
automatic-pix.canceled
{
"period": "MONTHLY",
"retryPolicy": "ACCEPT_3R_7D",
"authorizationId": "a7bc99ee-3333-4073-80e7-44aac8f99d5f",
"origin": "DEVELOPERS",
"link": {
"debtor": {
"taxId": "99999999999",
"name": "NOME",
"personType": "F"
},
"contract": "9997b90299999819f9c93dc5"
},
"externalId": "26dc999d-9f45-41ee-af07-be38a999999a",
"requests": [
{
"createdAt": "2025-07-28T17:53:07.955Z",
"canceledAt": "2025-07-28T17:54:20.964Z",
"authorizationId": "a7bc99ee-3333-4073-80e7-44aac8f99d5f",
"origin": "DEVELOPERS",
"recipient": {
"taxId": "9999999999",
"name": "NOME",
"personType": "F",
"account": {
"branchCode": "0001",
"number": "4379883-8",
"ispbParticipant": "18236120"
}
},
"integrationId": "SC3099999920250728d3d398eabe5",
"status": "CANCELED",
"expirationDate": "2025-08-14T03:00:00.000Z",
"updatedAt": "2025-07-28T17:54:20.964Z"
}
],
"initialDate": "2025-08-17",
"payee": {
"taxId": "99999999000999",
"desk": "PME",
"name": "NOME EMPRESA",
"personType": "J",
"account": {
"branchCode": "50",
"number": "099999736"
}
},
"createdAt": "2025-07-28T17:53:07.955Z",
"canceledAt": "2025-07-28T17:57:04.077Z",
"cancellationDescription": "Requested by the receiving user",
"activation": {
"journeyType": "WAITING_DEFINITION"
},
"useLineOfCredit": true,
"cancellationRequester": "PAYEE_USER",
"cancellationCode": "SLCR",
"status": "CANCELED",
"updatedAt": "2025-07-28T17:57:04.077Z"
}
automatic-pix.scheduling-paid
{
"additionalInformation": "Teste",
"amount": 4.5,
"firstTxId": "d1cc9c0023423483c1c9bfbe5bfcbc",
"schedulingId": "e234234c-1c64-465b-a433-a3423434011f",
"authorizationId": "13243244b-4d82-4551-8e99-2234234a9fe5",
"origin": "DEVELOPERS",
"scheduledDate": "2025-08-18",
"payer": {
"taxId": "***908447**",
"personType": "F",
"account": {
"branchCode": "1",
"number": "9444441",
"ispbParticipant": "18444440",
"portfolioCode": "1"
}
},
"installmentNumber": 2,
"payee": {
"taxId": "094444440162",
"desk": "PME",
"name": "TESTE",
"personType": "J",
"account": {
"branchCode": "50",
"number": "00444442",
"portfolioCode": "1"
}
},
"createdAt": "2025-08-14T20:05:25.000Z",
"confirmedAt": "2025-08-14T20:06:45.878Z",
"status": "PAID",
"amountPaid": 4.5,
"paidAt": "2025-08-18",
"movementId": "45444444cfe8d6ca74444449e",
"paymentEndToEndId": "E303444444181500138b71413bf",
"paymentTxId": "d1c44444463183c444444bfcbc",
"updatedAt": "2025-08-18T04:21:37.433Z"
}