Transferir por Chave Pix

Envie uma transferencia Pix utilizando a chave Pix do destinatario.

O header x-idempotency-key e essencial para evitar transferencias duplicadas. Sempre envie uma chave unica no header para cada transferencia. Se uma requisicao com a mesma x-idempotency-key for enviada novamente, a API retornara o resultado da transferencia original sem criar uma nova.

O campo payment e um objeto com currency (sempre "BRL") e amount em reais com decimais. Ex: 100.00 = R$ 100,00.

Quando priority for "HIGH", o campo creditorDocument (CPF/CNPJ do destinatario) e obrigatorio. Quando priority for "NORM" (padrao), o pagamento entra em fila e o campo expiration define o timeout em segundos.

POST/api/v2/pix/payments/dict

Realiza uma transferencia Pix para o destinatario identificado pela chave Pix informada.

Base URL: https://pagamentos.basspago.com.br

Headers

Header	Valor	Descricao
`Authorization`	Bearer {access_token}	Token de acesso obtido via OAuth2
`Content-Type`	application/json
`x-idempotency-key`	unique-key-123e4567-e89b-12d3-a456-426614174000	Chave unica para evitar transferencias duplicadas

Parametros do Body

Nome	Tipo	Obrigatorio	Descricao
`priority`	string	Opcional	"HIGH" ou "NORM" (padrao). HIGH = processamento instantaneo, NORM = enfileirado
`paymentFlow`	string	Opcional	"APPROVAL_REQUIRED" ou "INSTANT" (padrao). Define se o pagamento requer aprovacao antes de ser processado
`expiration`	integer	Opcional	Timeout da fila em segundos (1-10800, padrao 600). Aplica-se apenas quando priority e "NORM"
`payment`	object	Obrigatorio	Objeto com currency ("BRL") e amount (valor em reais com decimais). Ex: { "currency": "BRL", "amount": 100.00 }
`payment.currency`	string	Obrigatorio	Moeda do pagamento. Sempre "BRL"
`payment.amount`	number	Obrigatorio	Valor em reais com decimais. Ex: 100.00 = R$ 100,00
`pixKey`	string	Obrigatorio	Chave Pix do destinatario
`description`	string	Opcional	Descricao da transferencia
`creditorDocument`	string	Opcional	CPF ou CNPJ do destinatario. Obrigatorio quando priority e "HIGH"

Exemplo de Request

{
  "priority": "HIGH",
  "paymentFlow": "INSTANT",
  "expiration": 600,
  "payment": {
    "currency": "BRL",
    "amount": 100.00
  },
  "pixKey": "12345678900",
  "description": "Payment for services",
  "creditorDocument": "12345678900"
}

Exemplo de Response

{
  "id": "pay_abc123def456",
  "status": "PROCESSING",
  "priority": "HIGH",
  "paymentFlow": "INSTANT",
  "payment": {
    "currency": "BRL",
    "amount": 100.00
  },
  "description": "Payment for services",
  "pixKey": "12345678900",
  "creditorDocument": "12345678900",
  "idempotencyKey": "unique-key-123e4567-e89b-12d3-a456-426614174000",
  "createdAt": "2026-04-03T10: 30:00Z"
}

Exemplos de Codigo

curl -X POST \
  https://pagamentos.basspago.com.br/api/v2/pix/payments/dict \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \
  -H 'x-idempotency-key: unique-key-123e4567-e89b-12d3-a456-426614174000' \
  -d '{
    "priority": "HIGH",
    "paymentFlow": "INSTANT",
    "expiration": 600,
    "payment": {
      "currency": "BRL",
      "amount": 100.00
    },
    "pixKey": "12345678900",
    "description": "Payment for services",
    "creditorDocument": "12345678900"
  }'