Criar cobrança

Uma cobrança (charge) é uma tentativa de pagamento. Você envia o payload com os dados do pagador e do meio de pagamento, e recebe de volta o status e os dados para exibir ao cliente.

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

Cria uma cobrança com o meio de pagamento informado em type_charge.

Cobrança com Pix

Para Pix, informe os dados do pagador, o valor e o tempo de expiração. A resposta traz o payload copia-e-cola e o QR Code em base64.

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..."
}

Cobrança com cartão

A resposta do cartão é síncrona: você já recebe se foi aprovada (confirmed), recusada (unpaid) ou se exige autenticação 3DS (url_3ds).

Requisição

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

{
  "wallet_uuid": "00000000-0000-0000-0000-000000000000",
  "merchant_id": "MER-001",
  "payer_name": "João da Silva",
  "payer_tax_id": "12345678901",
  "payer_document_type": "CPF",
  "payer_email": "joao@example.com",
  "payer_cell_phone": "+5511999999999",
  "description": "Order #1234",
  "due_date": "2026-09-30",
  "installment_count": 3,
  "installment_value": 199.90,
  "currency": "BRL",
  "type_charge": "credit_card",
  "card_holder_name": "JOAO DA SILVA",
  "card_number": "4111111111111111",
  "card_expiry_month": "12",
  "card_expiry_year": "2030",
  "card_cvv": "123",
  "client_ip": "200.155.12.34",
  "webhook_url": "https://your-store.com/webhook/charge"
}

Resposta

{
  "charge_uuid": "c3d4e5f6-7a8b-9c0d-1e2f-3a4b5c6d7e8f",
  "local_currency": 199.90,
  "currency": "BRL",
  "usd_currency": 36.34,
  "type": "credit_card",
  "date": "2026-09-14 14:36:11",
  "description": "Order #1234",
  "due_date": "2026-09-30",
  "status": "confirmed",
  "message": "Transaction approved",
  "installment_count": 3,
  "installments": [
    { "installment": 1, "value": 66.63 },
    { "installment": 2, "value": 66.63 },
    { "installment": 3, "value": 66.64 }
  ]
}

Cobrança com boleto

Requisição

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

{
  "wallet_uuid": "00000000-0000-0000-0000-000000000000",
  "payer_name": "João da Silva",
  "payer_tax_id": "12345678901",
  "payer_document_type": "CPF",
  "payer_email": "joao@example.com",
  "description": "Service invoice",
  "due_date": "2026-10-05",
  "installment_value": 350.00,
  "currency": "BRL",
  "type_charge": "boleto",
  "webhook_url": "https://your-store.com/webhook/charge"
}

Resposta

{
  "charge_uuid": "d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f90",
  "local_currency": 350.00,
  "currency": "BRL",
  "usd_currency": 63.64,
  "type": "boleto",
  "date": "2026-09-14 14:37:03",
  "description": "Service invoice",
  "due_date": "2026-10-05",
  "status": "issued",
  "message": "Boleto generated",
  "installment_count": 1,
  "payment_payload": {
    "url": "https://pay.ddpay.tech/boleto/d4e5f6a7...",
    "digital_line": "34191.79006 01234.560041 01234.567006 8 99990000035000"
  },
  "charge_payment_url": "https://pay.ddpay.tech/charge/d4e5f6a7..."
}

Campos do payload

Os principais campos de uma cobrança:

Campo	Tipo	Obrigatório	Descrição
wallet_uuid	string	Sim	Carteira que recebe o valor.
payer_name	string	Sim*	Nome do pagador. *Obrigatório para Pix BR e cartão com 3DS.
payer_tax_id	string	Sim*	CPF/CNPJ do pagador. *Obrigatório para Pix BR.
payer_document_type	string	Não	CPF ou CNPJ; PAS (passaporte) para compradores do exterior.
payer_email	string	Não	E-mail do pagador.
payer_cell_phone	string	Não	Telefone do pagador com DDI.
description	string	Sim	Descrição visível ao pagador.
installment_value	number	Sim	Valor de cada parcela.
installment_count	integer	Não	Número de parcelas (padrão: 1).
due_date	date	Não	Data de vencimento (YYYY-MM-DD).
currency	string	Sim	Sempre BRL.
type_charge	string	Sim	Meio de pagamento: pix, boleto, credit_card, debit_card, e_wallet, applepay, googlepay.
card_holder_name	string	Cond.	Titular do cartão (apenas em cobranças de cartão).
card_number	string	Cond.	Número do cartão (apenas em cobranças de cartão).
card_expiry_month	string	Cond.	Mês de validade do cartão (MM).
card_expiry_year	string	Cond.	Ano de validade do cartão (YYYY).
card_cvv	string	Cond.	Código de segurança do cartão (apenas em cobranças de cartão).
expiration_seconds	integer	Não	Tempo de expiração do Pix (sandbox: 1 a 3600 s).
client_ip	string	Não	IP do pagador, usado nas regras de risco do cartão.
webhook_url	string	Não	URL que recebe notificações de mudança de status.