Legacy: PIX Payment (Cashout)

Endpoint legado para envio de PIX

Endpoint legado — será desabilitado em breve. Migre para POST /v2/transactions/cashout o quanto antes. Após a data de descontinuação, esta rota retornará 410 Gone e novas integrações devem usar exclusivamente o endpoint moderno.

Requer autenticação

POST/v2/pix/payment

Envia um PIX para uma chave PIX de destino.

Parâmetros

amountnumberobrigatório

Valor a enviar em BRL.

creditPartyobjectobrigatório

Dados da chave PIX de destino.

creditParty.keyTypestringobrigatório

Tipo da chave: CPF, CNPJ, EMAIL, PHONE, EVP.

creditParty.keystringobrigatório

Valor da chave PIX.

descriptionstring

Descrição do pagamento.

external_idstring

ID único no seu sistema para idempotência.

Rate limit

6 000 reqs/min por credencial (mesmo limite do /v2/transactions/cashout moderno).

Erros

Código	HTTP	Descrição
`MISSING_REQUIRED_FIELD`	400	Campo obrigatório ausente
`MISSING_SIGNATURE` / `INVALID_SIGNATURE`	401	HMAC ausente ou inválido
`INVALID_PIX_KEY`	422	Chave PIX malformada
`PIX_KEY_NOT_FOUND`	422	Chave PIX não encontrada no DICT
`INSUFFICIENT_BALANCE`	422	Saldo insuficiente
`BELOW_MIN_LIMIT`	409	Abaixo do mínimo
`EXCEEDS_MAX_LIMIT`	409	Acima do máximo
`LIMIT_EXCEEDED`	409	Limite diário atingido
`DUPLICATE_EXTERNAL_ID`	409	`external_id` já utilizado
`PROVIDER_ERROR`	502	Erro no provedor — retryable

cURL

PHP

JavaScript

Python

curl -X POST https://api.bspay.co/v2/pix/payment \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50.00,
    "creditParty": {
      "keyType": "CPF",
      "key": "12345678901"
    },
    "description": "Pagamento de serviço",
  }'

Resposta 200

{
  "success": true,
  "message": "SUCCESS",
  "transaction_id": "af8484b6c151f5580348f11d356d9e19",
  "request_id": "21617f49b10484b25acc9d85",
  "timestamp": "2026-04-04T13:20:15Z"
}

Resposta 400 — Campo obrigatório ausente

{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELD",
    "message": "A required field is missing.",
    "group": "VALIDATION",
    "retryable": false,
    "details": {
      "fields": ["creditParty"]
    }
  }
}

AnteriorLegacy: PIX QR CodePróximoLegacy: Consultar Transação