Começando

Neste guia você cria a sua primeira cobrança funcional em menos de cinco minutos. Pegue as credenciais do ambiente sandbox e siga o passo a passo.

1. Obtenha seu token

POST/api/v1/bff/account/session

Autentique com as credenciais da sua conta e receba um JWT Bearer token.

Obtenha o token

curl -s -X POST https://sandbox.api.ddpay.tech/api/v1/bff/account/session \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your_user",
    "password": "your_password"
  }'

# response:
# {
#   "access_token": "eyJhbGciOiJSUzI1NiIs...",
#   "expires_in": 3600
# }

2. Faça sua primeira cobrança

Envie um payload de cobrança para a carteira. Veja com Pix — sem dados de cartão, confirmado no sandbox em segundos:

POST/api/v1/bank/wallet/charge/

Cria uma cobrança. Retorna o status e todo o payload de pagamento.

Requisição

POST /bank/wallet/charge/
Authorization: Bearer <token>
Content-Type: application/json

{
  "wallet_uuid": "00000000-0000-0000-0000-000000000000",
  "payer_name": "Maria Oliveira",
  "payer_tax_id": "98765432109",
  "payer_document_type": "CPF",
  "payer_cell_phone": "+5521998765432",
  "description": "Monthly subscription",
  "installment_value": 49.90,
  "currency": "BRL",
  "type_charge": "pix",
  "expiration_seconds": 3600,
  "webhook_url": "https://your-store.com/webhook/charge"
}

Resposta

{
  "charge_uuid": "b2c3d4e5-6f7a-8b9c-0d1e-f2a3b4c5d6e7",
  "local_currency": 49.90,
  "currency": "BRL",
  "usd_currency": 9.07,
  "type": "pix",
  "date": "2026-09-14 14:35:00",
  "description": "Monthly subscription",
  "due_date": "2026-09-14 15:35:00",
  "status": "issued",
  "message": "Pix generated",
  "installment_count": 1,
  "payment_payload": {
    "payload": "00020126580014BR.GOV.BCB.PIX0136abcd...5204000053039865national",
    "qr_code": "iVBORw0KGgoAAAANSUhEUgAA... (base64)",
    "expiration_date": "2026-09-14 15:35:00"
  },
  "charge_payment_url": "https://pay.ddpay.tech/charge/b2c3d4e5..."
}

3. Receba a notificação

Quando o status da cobrança mudar, a plataforma envia um webhook para a URL que você configurou. Veja a seção Webhooks para o formato completo.