Create a payout

Sends money from your balance to a Pix key. The call returns as soon as the payout is accepted; the final result arrives as a payout.paid or payout.failed event.

POST/payouts

Headers

AuthorizationBasic

Required

client_id:api_key

Idempotency-Keystring

Required

Unique per payout. Retrying with the same key never pays twice

Armhed-Operation-Tokenstring

Optional token with scope payouts:create

Body

amountinteger

Required

Cents, 1 to 100000000 (R$ 1.000.000,00)

pix_key.typestring

cpf, cnpj, email, phone or random

pix_key.keystring

The key itself (up to 140 characters). Omit pix_key to pay the bank account registered on your account

recipient.namestring

Beneficiary name

recipient.documentstring

Beneficiary CPF or CNPJ. Defaults to your company document

descriptionstring

Up to 140 characters

metadataobject

Any JSON, returned on the payout and its events

Requestbash

curl https://api.armhed.lat/payouts -u "$CLIENT_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payout-77" \
  -d '{
    "amount": 2500,
    "pix_key": { "type": "cpf", "key": "50651470862" },
    "recipient": { "name": "Bruno Lima", "document": "50651470862" },
    "description": "Seller settlement #77",
    "metadata": { "seller_id": 912 }
  }'

Response

201 Createdjson

{
  "object": "payout",
  "id": "1390",
  "idempotency_key": "payout-77",
  "status": "processing",
  "amount": 2500,
  "currency": "BRL",
  "description": "Seller settlement #77",
  "pix_key": { "type": "CPF", "key": "50651470862" },
  "recipient": { "name": null, "document": "50651470862" },
  "end_to_end_id": null,
  "failure": null,
  "metadata": { "seller_id": 912 },
  "created_at": "2026-10-31T12:10:00Z",
  "updated_at": "2026-10-31T12:10:00Z",
  "paid_at": null
}

statusstring

pending (queued), processing (sent to the bank), paid, failed, or returned (the bank sent the money back)

recipient.namestring

Filled with the name the bank confirms once paid

end_to_end_idstring

Central Bank transaction id, once paid

failureobject

code and message from the bank when status is failed

Common errors

400 invalid_request

Missing Idempotency-Key, amount out of range, invalid pix_key.type, no Pix key and no registered bank account, or insufficient balance (amount plus fee)

403 forbidden

The calling IP is not in your payout allowlist

409 conflict

A payout with this Idempotency-Key is still being processed

503 unavailable

Payouts are temporarily unavailable; retry with the same key