Getting started

In this guide you create your first working charge in less than five minutes. Grab your sandbox credentials and follow the steps.

1. Get your token

POST/api/v1/bff/account/session

Authenticate with your account credentials and receive a JWT Bearer token.

Get the 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. Make your first charge

Send a charge payload to the wallet. Here is one with a credit card:

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

Creates a charge. Returns the approval status and the full payment payload.

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

3. Get notified

When the charge status changes, the platform sends a webhook to the URL you configured. See the Webhooks section for the full format.