Realize sua primeira transferência

Com os certificados de Cash Out e o Bearer Token em mãos, vamos criar a sua primeira transferência.

Toda requisição de Cash Out usa a base URL https://pagamentos.basspago.com.br e os certificados e Bearer Token de Cash Out. Precisa do token? Volte para Autenticação.

Endpoint

POST https://pagamentos.basspago.com.br/api/v2/pix/payments/dict

Certificados e headers

Envie os certificados de Cash Out e a senha na requisição:

--cert ./client.crt \
--key ./client.key \
--pass "SUA_SENHA_DO_CERTIFICADO"

E os headers de autenticação, incluindo o x-idempotency-key:

-H "Content-Type: application/json" \
-H "Authorization: Bearer {access_token}" \
-H "x-idempotency-key: {chave_unica}"

O x-idempotency-key é uma chave única por transferência. Ele evita transferências duplicadas: se a mesma chave for reenviada, a transferência não é processada de novo.

Parâmetros do body

string

Opções: HIGH ou NORM. Padrão: NORM.Com HIGH, o pagamento é processado instantaneamente e retornado na própria requisição (a requisição fica aberta até a transferência ser concluída). Com NORM, o pagamento é enfileirado e, após o processamento, o resultado é enviado por webhook.

string

Opções: APPROVAL_REQUIRED ou INSTANT. Padrão: INSTANT.Com APPROVAL_REQUIRED, a transferência precisa de confirmação adicional para ser aprovada. Com INSTANT, a transferência é executada instantaneamente, sem necessidade de aprovação.

integer

Tempo em segundos que o saque pode ficar na fila de transferência antes de ser cancelado. Entre 1 e 10800. Só se aplica quando priority for NORM. Padrão: 600.

string

required

Moeda corrente do pagamento. Deve ser sempre "BRL".

number

required

Valor da transferência. Exemplo: 50.00.

string

required

Chave Pix da conta de destino.

string

Descrição da transferência.

string

CPF ou CNPJ da conta de destino. Obrigatório quando priority for HIGH.

Formato de cada tipo de chave

Tipo	Formato	Exemplo
CPF	String limpa, apenas os números	`12312312300`
CNPJ	String limpa, apenas os números	`12123123000102`
Telefone	Prefixo `+55`, sem espaços ou caracteres especiais	`+55DDDNUMERO`
E-mail	String em formato de e-mail	`email@email.com`
EVP	Chave EVP (aleatória) gerada	`5c490e78-78f0-4b09-a5f3-02c699a00111`

Exemplo de requisição

curl -X POST "https://pagamentos.basspago.com.br/api/v2/pix/payments/dict" \
  --cert ./client.crt \
  --key ./client.key \
  --pass "SUA_SENHA_DO_CERTIFICADO" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}" \
  -H "x-idempotency-key: 6a1f2e3d-4c5b-6a7f-8e9d-0a1b2c3d4e5f" \
  -d '{
    "priority": "NORM",
    "paymentFlow": "INSTANT",
    "expiration": 600,
    "payment": {
      "currency": "BRL",
      "amount": 150.00
    },
    "pixKey": "5c490e78-78f0-4b09-a5f3-02c699a00111",
    "description": "Pagamento ao fornecedor",
    "creditorDocument": "22255588896"
  }'

Exemplo de resposta

{
  "id": "pay_9f8e7d6c5b4a",
  "status": "PROCESSING",
  "priority": "NORM",
  "paymentFlow": "INSTANT",
  "payment": {
    "currency": "BRL",
    "amount": 150.00
  },
  "description": "Pagamento ao fornecedor",
  "pixKey": "5c490e78-78f0-4b09-a5f3-02c699a00111",
  "creditorDocument": "22255588896",
  "idempotencyKey": "6a1f2e3d-4c5b-6a7f-8e9d-0a1b2c3d4e5f",
  "createdAt": "2026-07-21T14:40:00Z"
}

Webhooks de transferências

Se você cadastrou corretamente os webhooks de transferência no FINANCE, receberá notificações sempre que uma transferência tiver uma atualização. Veja os principais eventos e seus campos.

Transferência realizada
Transferência rejeitada

{
  "data": {
    "id": 731055,
    "txId": null,
    "pixKey": null,
    "status": "LIQUIDATED",
    "payment": {
      "amount": "250.00",
      "currency": "BRL"
    },
    "endToEndId": "E87654321202607211035a1b2c3d4e5f",
    "webhookType": "TRANSFER",
    "debtorAccount": {
      "ispb": "87654321",
      "name": "SUA LOJA LTDA",
      "issuer": "0000",
      "number": "0000",
      "document": "12345678000199",
      "accountType": "TRAN"
    },
    "creditorAccount": {
      "ispb": "12345678",
      "name": "CARLOS HENRIQUE SOUZA",
      "issuer": "0001",
      "number": "45678912",
      "document": "11144477735",
      "accountType": "CACC"
    },
    "creditDebitType": "DEBIT",
    "localInstrument": "DICT",
    "transactionType": "PIX",
    "createdAt": "2026-07-21T10:35:00.000Z"
  },
  "type": "TRANSFER"
}

Campo	Tipo	Descrição
`data.id`	integer	Identificador da transferência na Super Finance.
`data.txId`	string \| null	Identificador da cobrança, quando houver.
`data.pixKey`	string \| null	Chave Pix envolvida, quando houver.
`data.status`	string	Status da transferência (`LIQUIDATED`).
`data.payment.amount`	string	Valor transferido.
`data.payment.currency`	string	Moeda (ex.: `BRL`).
`data.endToEndId`	string	Identificador end-to-end do Pix.
`data.webhookType`	string	Tipo do webhook (`TRANSFER`).
`data.debtorAccount`	object	Dados da conta pagadora (sua conta).
`data.creditorAccount`	object	Dados da conta de destino.
`data.creditDebitType`	string	`CREDIT` ou `DEBIT`.
`data.localInstrument`	string	Forma do Pix (ex.: `DICT`).
`data.transactionType`	string	Tipo da transação (ex.: `PIX`).
`data.createdAt`	string	Data e hora do evento (ISO 8601).
`type`	string	Tipo do evento (`TRANSFER`).

{
  "data": {
    "id": 731056,
    "txId": null,
    "pixKey": null,
    "status": "REJECTED",
    "payment": {
      "amount": "500.00",
      "currency": "BRL"
    },
    "endToEndId": "E87654321202607211100f6e5d4c3b2a",
    "errorMessage": "Conta do destinatário encerrada",
    "webhookType": "CASHOUT",
    "debtorAccount": {
      "ispb": "87654321",
      "name": "SUA LOJA LTDA",
      "issuer": "0000",
      "number": "0000",
      "document": "12345678000199",
      "accountType": "TRAN"
    },
    "creditorAccount": {
      "ispb": "12345678",
      "name": "MARIANA COSTA LIMA",
      "issuer": "0001",
      "number": "87654321",
      "document": "22255588896",
      "accountType": "CACC"
    },
    "creditDebitType": "DEBIT",
    "localInstrument": "DICT",
    "transactionType": "PIX",
    "createdAt": "2026-07-21T11:00:00.000Z"
  },
  "type": "CASHOUT"
}

Campo	Tipo	Descrição
`data.id`	integer	Identificador da transferência na Super Finance.
`data.txId`	string \| null	Identificador da cobrança, quando houver.
`data.pixKey`	string \| null	Chave Pix envolvida, quando houver.
`data.status`	string	Status da transferência (`REJECTED`).
`data.payment.amount`	string	Valor da transferência rejeitada.
`data.payment.currency`	string	Moeda (ex.: `BRL`).
`data.endToEndId`	string	Identificador end-to-end do Pix.
`data.errorMessage`	string	Motivo da rejeição.
`data.webhookType`	string	Tipo do webhook (`CASHOUT`).
`data.debtorAccount`	object	Dados da conta pagadora (sua conta).
`data.creditorAccount`	object	Dados da conta de destino.
`data.creditDebitType`	string	`CREDIT` ou `DEBIT`.
`data.localInstrument`	string	Forma do Pix (ex.: `DICT`).
`data.transactionType`	string	Tipo da transação (ex.: `PIX`).
`data.createdAt`	string	Data e hora do evento (ISO 8601).
`type`	string	Tipo do evento (`CASHOUT`).

Tudo pronto 🎉

Pronto, agora você tem um setup básico configurado, com pagamentos e transferências. Explore o restante da nossa documentação e conheça funcionalidades mais específicas.

Guia de implementação

Transações

Transferências

Contestações

Realize sua primeira transferência

Endpoint

Certificados e headers

Parâmetros do body

Formato de cada tipo de chave

Exemplo de requisição

Exemplo de resposta

Webhooks de transferências

Tudo pronto 🎉

​Endpoint

​Certificados e headers

​Parâmetros do body

​Formato de cada tipo de chave

​Exemplo de requisição

​Exemplo de resposta

​Webhooks de transferências

​Tudo pronto 🎉

Endpoint

Certificados e headers

Parâmetros do body

Formato de cada tipo de chave

Exemplo de requisição

Exemplo de resposta

Webhooks de transferências

Tudo pronto 🎉