Withdrawals & transfers

A payout moves the balance held in your name to your own bank account (withdrawal) or to a registered seller (split transfer). Diamond Pay never holds the funds.

POST/api/v1/bank/payout/

Creates a withdrawal or transfer from the wallet to the destination set in <type>_destination.

Request

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

{
  "wallet_uuid": "00000000-0000-0000-0000-000000000000",
  "merchant_id": "MER-001",
  "type_payout": "pix",
  "value": 1500.00,
  "currency": "BRL",
  "description": "Withdrawal to bank account",
  "transaction_reference": "REF-0001",
  "pix_destination": {
    "pix_address_key": "12345678000199",
    "pix_address_key_type": "cnpj",
    "beneficiary_name": "Sua Loja LTDA",
    "beneficiary_tax_id": "12345678000199"
  },
  "webhook_url": "https://your-store.com/webhook/payout"
}

Response

{
  "payout_uuid": "1c2d3e4f-5a6b-7c8d-9e0f-a1b2c3d4e5f6",
  "status": "pending",
  "type_payout": "pix",
  "amount": 1500.00,
  "currency": "BRL",
  "description": "Withdrawal to bank account",
  "transaction_reference": "REF-0001",
  "fee": 2.50
}

Supported destinations

type_payout	Destination	Destination field
pix	Pix key of an account in your name	pix_destination (pix_address_key + key_type)
bank_transfer	Bank account in the same name	bank_destination
ted	TED to an account in the same name	bank_destination
internal	Split transfer between accounts of the same entity	internal_destination

Payout status

Status	What it means
pending	Awaiting processing.
issued	Payout issued.
processing	Processing at the intermediary.
realized	Completed: amount delivered.
returned	Returned (invalid key, wrong data).
canceled	Canceled before execution.
error	Processing failure.

GET/api/v1/bank/payout/<payout_uuid>/<wallet_uuid>/

Returns the current status of a payout by id.