Pagamentos e Transferências

A API de Pagamentos e transferências permite que você efeitue pagamentos de diversos tipos e realize transferências de PIX, TED, TEF. Esta API permite também realizar o cancelamento e a listagem dos pagamentos e transferências.

Casos de Uso

• Inserir numa plataforma a possibilidade de pagar contas.
• Receber notificações de pagamentos.

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

Idempotência

A API de pagamentos e transferência do BTG Pactual Empresas utiliza a idempotência como forma de garantir que você possa repetir uma requisição, em casos adversos como por exemplo uma perda de conexão, sem o risco de duplicar uma operação.

Isto é feito por meio de um header x-idempotency-key.

• x-idempotency-key é utilizado para passar a chave de idempotência definida pelo usuário. Aceita qualquer valor.

A chave presente em x-idempotency-key ficará atrelada ao operador que emitiu o token. Assim, operadores diferentes podem usam a mesma chave, contanto que estejam utilizando token diferentes.

Recomendamos que seja utilizado um uuid para cada requisição que posteriormente será armazenado por vocês para controle. Assim, caso não haja resposta da API e o mesmo uuid seja utilizado, a requisição não será duplicada.

📘

Exemplo

cURL

curl --location 'https://api.empresas.btgpactual.com/1111111111/banking/payments?pageSize=10&pageNumber=1' \
--header 'Authorization: ••••••' \
--header 'x-idempotency-key: f08jjj6b-00bc-1e3e-ad99-acb353333914'

Caso não seja enviado o x-idempotency-key, a API entenderá que não deseja utilizar a idempotência e, assim, assumirá o comportamento padrão.

Escopos necessários

O token para consumir a API de Pagamentos deve ser gerado usando o Authorization Code.

O escopo openidé obrigatório. Ele permite consultar o perfil do usuário BTG com acesso à conta.

É necessário escolher um dos seguintes escopos:

Recursos Disponíveis

Os recursos da API de Pagamentos estão disponíveis no API Reference.

📘

API Reference

Pagamentos e Transferências

Modalidades de pagamentos e transferências

A API de pagamentos de transferências oferecem uma serie de modalidades de pagamento, diferenciando entre si somente nos dados enviados no corpo da requisição dentro do objeto details e no tipo selecionado.

PIX_QR_CODE

Esta modalidade exige que seja informado dentro do details o emv, também chamado de código do copia e cola, do QR code. Esta modalidade cria uma iniciação de um pagamento ou transferência do tipo PIX.

BANKSLIP

Esta modalidade exige que seja informado dentro do details a linha digitável digitableLine do boleto a ser pago. Não aceita linhas digitáveis que se iniciam com 8

UTILITIES

Esta modalidade exige que seja informado dentro do details a linha digitável digitableLine da conta de utilidades(conta de energia, água...) ou FGTS a ser pago. Aceita linhas digitáveis que se iniciam com 8.

TED e PIX_MANUAL

Esta modalidade exige que seja informado dentro do details as informações da conta do beneficiário do pagamento ou transação. O tipo do pagamento ou transferência depende do tipo informado:

• PIX_MANUAL consiste num PIX
• TED consiste em um TED ou TEF com base no que é informado.

PIX_KEY

Esta modalidade exige que seja informado dentro do details uma chave pix válida de qualquer tipo. Origina um pagamento ou transferência do tipo PIX

DARF

Esta modalidade exige que sejam informados dentro do details as informações do documento a ser pago.

PIX_REVERSAL

Esta modalidade exige que seja informado dentro do details o originalEndToEndId do pix recebido. Esta modalidade consiste em uma devolução de pix recebido para a conta de onde se originou a transação.

Status de pagamentos e máquina de estados

Um pagamento pode ter diversos status antes e depois de ser aprovado.

Antes da aprovação, um pagamento pode exibir os seguintes status:

Depois de receber o status Authorized, um pagamento pode exibir os seguintes status:

Os status CANCELED, FAILED e REVERTED não podem ser revertidos. Ao receber esses status, um pagamento é fechado.

O status CONFIRMED indica que houve débito na conta de origem, mas pode ser estornado:

Eventos de webhook

Eventos possíveis

payments.*

{
    "paymentId": "0d0000ac-0c00-0dd0-b00d-00c0e00a00cd",
    "category": "BANKSLIP", //Categoria do pagamentos 
    "type": "BANKSLIP", //Tipo de pagamento
    "amount": 1.01,
    "scheduledDate": "2024-02-19",
    "debitParty": {
        "taxId": "00000080000000",
        "name": "NOME DA PARTE DEBITADA",
        "number": "000000000",
        "branchCode": "50",
        "bankCode": "208"
    },
    "detail": {
        "digitableLine": "000000000900000000008000000000000000000000000000",
        "barcode": "00000000000000000000800000000000000000000000",
        "dueDate": "2024-02-21",
        "payee": {
            "socialName": "NOME SOCIAL DO PAGADOR",
            "fantasyName": "NOME DA EMPRESA DO PAGADOR",
            "taxId": "00000000000000",
            "bankCode": "001"
        }
    },
    "tags": {
        "externalId": "TAG PARA IDENTIFICAR"
    }
}

payments.confirmed no caso de PIX

{
    "paymentId": "999ed999-e2e3-999b-abdd-b6dc9999ef1d",
    "type": "PIX_KEY", //Pode assumir o valor de qualquer um dos tipos de PIX
    "amount": 1,
    "scheduledDate": "2024-06-04",
    "paymentDate": "2024-06-04",
    "status": "CONFIRMED",
    "debitParty": {
        "taxId": "9999995980990112",
        "name": "EXEMPLO",
        "number": "0099999941",
        "branchCode": "50",
        "bankCode": "208"
    },
    "detail": {
        "creditParty": {
            "taxId": "499999990009999",
            "name": "Criar Agencia",
            "account": {
                "type": "CC",
                "number": "39999919",
                "branch": "1",
                "bankCode": "999",
                "ispb": "99899899096"
            }
        },
        "key": {
            "type": "TAX_ID",
            "value": "9999995999915"
        },
        "endToEndId": "E9999999999041446999999d16d"
    },
    "tags": {}
}

payments.approval-...

Eventos possíveis

{
    "approvalId": "c0111111-81ae-333a-2222-ea67a7b111111",
    "taxId": "31342341005555",
    "amount": 1.45,
    "status": "Authorization", //status referente ao status da aprovação de pagamento
    "createdAt": "2024-05-23",
    "updatedAt": "2024-05-23",
    "items": [
        {
            "paymentId": "j00009f7-2386-4ed1-5555-4c93444444fa9",
            "category": "PIX_MANUAL",
            "type": "PIX_MANUAL",
            "amount": 147.45,
            "scheduledDate": "2024-05-23",
            "debitParty": {
                "taxId": "333311111115",
                "name": "name",
                "number": "003854324",
                "branchCode": "50",
                "bankCode": "208"
            },
            "detail": {
                "creditParty": {
                    "taxId": "21234123435",
                    "name": "EMERSON FLORES",
                    "account": {
                        "type": "CC",
                        "number": "133338",
                        "branch": "895",
                        "bankCode": "237",
                        "ispb": "60746948"
                    }
                }
            },
            "tags": {
                "externalId": "d2j4"
            }
        }
    ],
    "tags": {}
}

Códigos de erro

Abaixo estão os erros possíveis ao realizar uma requisição na API juntamente com as suas descrições. Todos os erros estarão prefixados na response com btg:enterprise:banking:payments