API Reference
Start typing to search…

Pagamentos Recorrentes

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 Pagamentos recorrentes deve ser gerado usando o Authorization Code.

É necessário incluir um dos seguintes escopos:

EscopoDescrição
empresas.btgpactual.com/payments(ESCOPO DEPRECADO)Permite a consulta e emissão de pagamentos
brn:btg:empresas:banking:paymentsPermite a consulta e emissão de pagamentos

Especificidades

QR CODE

Só é possível realizar a recorrência de QR Codes ESTÁTICOS. QR Codes dinâmicos não estão aptos a realizar a recorrência.

PIX_AUTOMATIC

A realização do PIX_AUTOMATIC só é possível quando o basePayment.type é PIX_QR_CODE e representa a JORNADA 2 do produto de pix automático do BACEN Pix Automático.


Eventos de webhook

A propriedade "detail" assumirá o formato referente ao seu "type". Consulte a API Reference de Criar iniciação de pagamento ou transferência

Eventos possíveis

EventosDescrição
payments.recurrence-dispatchedRecorrência despachada
payments.recurrence-createdRecorrência de pagamento criada
payments.recurrence-approvedRecorrência de pagamento aprovada

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

payments.recurrence-dispatched

{
  "eventType": "DISPATCHED_RECURRENCE_EVENT",
  "id": "eb269755-e8d0-4651-ba10-80dcea8f733d",
  "type": "PIX_AUTOMATIC",
  "systemOrigin": "RAPI",
  "status": "DISPATCHED",
  "periodicity": {
    "type": "MONTHLY",
    "detail": {
      "startDate": "2025-06-13"
    }
  },
  "basePayment": {
    "type": "PIX_AUTOMATIC",
    "amount": 889.04,
    "debitParty": {
      "taxId": "37297902000141",
      "name": "VECHI CONSULTORIA E PROJETOS LTDA",
      "account": {
        "type": "CC",
        "number": "003886850",
        "branch": "50",
        "bankCode": "208"
      }
    },
    "detail": {
      "creditParty": {
        "taxId": "99999918999924",
        "name": "Pix Tester 918"
      }
    }
  },
  "detail": {
    "pixRecurrenceId": "RR999999182025061382855162808",
    "ispb": "99999918",
    "recurringChargeId": "25477622",
    "allowOverdraftUsage": false,
    "debtor": {
      "name": "BANCO BTG PACTUAL S.A.",
      "taxId": "30306294000145"
    },
    "shouldNotifyScheduling": true,
    "journey": "ONE"
  }
}

payments.recurrence-approved

{
    "eventType": "APPROVED_RECURRENCE_EVENT",
    "id": "eb269755-e8d0-4651-ba10-80dcea8f733d",
    "type": "PIX_AUTOMATIC",
    "systemOrigin": "RAPI",
    "status": "APPROVED",
    "periodicity": {
        "type": "MONTHLY",
        "detail": {
            "startDate": "2025-06-13"
        }
    },
    "basePayment": {
        "type": "PIX_AUTOMATIC",
        "amount": 889.04,
        "debitParty": {
            "taxId": "37297902000141",
            "name": "VECHI CONSULTORIA E PROJETOS LTDA",
            "account": {
                "type": "CC",
                "number": "003886850",
                "branch": "50",
                "bankCode": "208"
            }
        },
        "detail": {
            "creditParty": {
                "taxId": "99999918999924", //masked taxId
                "name": "Pix Tester 918"
            }
        }
    },
    "detail": {
        "pixRecurrenceId": "RR999999182025061382855162808",
        "ispb": "99999918",
        "recurringChargeId": "25477622",
        "allowOverdraftUsage": false,
        "debtor": {
            "name": "BANCO BTG PACTUAL S.A.",
            "taxId": "30306294000145"
        },
        "shouldNotifyScheduling": true,
        "journey": "ONE"
    }
}

payments.recurrence-created

{
    "eventType": "CREATED_RECURRENCE_EVENT",
    "id": "08357984-2e78-4500-8acf-f2b5eaaf359a",
    "type": "PIX_AUTOMATIC",
    "systemOrigin": "RAPI",
    "status": "CREATED",
    "periodicity": {
        "type": "MONTHLY",
        "detail": {
            "startDate": "2025-06-16",
            "endDate": "2025-07-16"
        }
    },
    "basePayment": {
        "type": "PIX_AUTOMATIC",
        "amount": 0.25,
        "debitParty": {
            "taxId": "37297902000141",
            "name": "VECHI CONSULTORIA E PROJETOS LTDA",
            "account": {
                "type": "CC",
                "number": "003886850",
                "branch": "50",
                "bankCode": "208"
            }
        },
        "detail": {
            "creditParty": {
                "taxId": "47328649000108",
                "name": "INSTITUTO PACTO PELO ESPORTE"
            }
        }
    },
    "detail": {
        "pixRecurrenceId": "RN30306294202506137f5050eefa4",
        "ispb": "30306294",
        "recurringChargeId": "teste sender",
        "allowOverdraftUsage": false,
        "debtor": {
            "name": "vechi",
            "taxId": "37297902000141"
        },
        "shouldNotifyScheduling": true,
        "journey": "ONE"
    }
}