Segurança

📘
BTG Id
O Authorization Server do BTG Empresas se chama BTG Id. Usando o BTG Id, um aplicativo parceiro consegue consentimento e autorização para executar operações nas APIs do BTG em nome do cliente. Para saber mais, acesse a documentação do BTG Id

Escopos necessários

O token para consumir a API de Pix automático deve ser gerado usando o Authorization Code.

É necessário incluir o seguinte escopo:

Escopo	Descrição
brn:btg:empresas:banking:collections	Permite a consulta e gestão de cobrança

Jornadas do Pix Automático

Esta API comporta as jornadas 1, 2 e 3 do Pix Automático.

As instruções para a utilização de cada uma das jornadas será encontrada no endpoint de Criar Autorização de Pix Automático

Especificidades

Autorização com valor variável

Para a emissão de autorização de pix automático com valor variável é necessário que o campo amount não seja enviado. Desta maneira, o sistema irá inferir que não um valor fixo.

Eventos de webhook da Jornada 3

A Jornada 3 do Pix Automático conta com dois componentes de pagamento:

Pagamento imediato de um Pix QR Code.
Pagamento da recorrência conforme intervalo definido via API.

Estes componentes disparam eventos DIFERENTES quando ocorrem, sendo eles:

Para o pagamento imediato é disparado o evento instant-collections.paid conforme Pix cobrança dinâmico. Sendo assim, é necessário que seja dado o consentimento para a API de Pix cobrança dinâmico, conforme descrito em Webhooks.
Para o pagamento da recorrência é disparado o evento automatic-pix.scheduling-paid.

Eventos de webhook

Os payloads disponíveis abaixo representam o conteúdo do campo data, seguindo o formato do envio descrito em Eventos.

Evento	Descrição
`automatic-pix.authorization-created`	Autorização de pix automático criada.
`automatic-pix.scheduling-approved`	Agendamento de pix automático aprovado.
`automatic-pix.authorization-rejected`	Autorização de pix automático rejeitada.
`automatic-pix.cancelled`	Cancelamento no fluxo de pix automático.
`automatic-pix.scheduling-paid`	Pagamento de agendamento 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"
  }