Create a charge

A charge is a payment attempt. You send the payload with the payer data and the payment method, and receive back the status and the data to present to the customer.

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

Creates a charge with the payment method set in type_charge.

Pix charge

For Pix, provide payer data, the amount and the expiry window. The response brings the copy-paste payload and the QR Code in base64.

Request

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

Response

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

Card charge

The card response is synchronous: you already get whether it was approved (confirmed), declined (unpaid) or requires 3DS authentication (url_3ds).

Request

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

Response

{
  "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 }
  ]
}

Boleto charge

Request

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

Response

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

Payload fields

The main charge fields:

Field	Type	Required	Description
wallet_uuid	string	Yes	Wallet that receives the amount.
payer_name	string	Yes*	Payer name. *Required for BR Pix and 3DS cards.
payer_tax_id	string	Yes*	Payer CPF/CNPJ. *Required for BR Pix.
payer_document_type	string	No	CPF, CNPJ, DNI, CUIT, CUIL, CURP, RFC, INE or PAS.
payer_email	string	No	Payer email.
payer_cell_phone	string	No	Payer phone with country code.
description	string	Yes	Description shown to the payer.
installment_value	number	Yes	Value of each installment.
installment_count	integer	No	Number of installments (default: 1).
due_date	date	No	Due date (YYYY-MM-DD).
currency	string	Yes	ISO 4217 code, e.g. BRL, USD, MXN.
type_charge	string	Yes	Payment method: pix, boleto, credit_card, debit_card, e_wallet, spei, oxxo, qra, applepay, googlepay.
card_holder_name	string	Cond.	Card holder name (card charges only).
card_number	string	Cond.	Card number (card charges only).
card_expiry_month	string	Cond.	Card expiry month (MM).
card_expiry_year	string	Cond.	Card expiry year (YYYY).
card_cvv	string	Cond.	Card security code (card charges only).
expiration_seconds	integer	No	Pix expiry window (sandbox: 1 to 3600 s).
client_ip	string	No	Payer IP, used by card risk rules.
webhook_url	string	No	URL that receives status change notifications.