● Payouts · /v1

Payouts

Send money to a beneficiary. Signing requirements are one level stricter than for payments (L2 asymmetric signing), and account details must be encrypted in transit.

List payouts

GET /v1/payouts

Query parameters

status string
cursor string The page.next_cursor returned by the previous page
limit integer

Response 200

data object[]
└uid string
└reference_id string
└amount integer
└currency string
└currency_exponent integer
└status created | processing | paid | failed | returned
└connector_code string
└failure_code string
└created_at string<date-time>
page object
└next_cursor string
└has_more boolean
Request
curl -X GET https://api.baton.example/v1/payouts \
  -H "Authorization: Bearer sk_live_xxx"

Create a payout

POST /v1/payouts

Payouts carry the largest loss exposure, so signing is one level stricter: Ed25519 asymmetric signatures (L2) are mandatory and the beneficiary account must arrive inside an encrypted envelope, never in plaintext. Amounts over your configured threshold go to dual approval, returning status=created while they wait.

Headers

Idempotency-Keyrequired string A unique string you generate (UUID/ULID recommended). Replaying the same key within 24 hours returns the original result and never creates a second payment.

Body

reference_idrequired string
amountrequired integer
currencyrequired string
beneficiaryrequired object Account fields must sit inside the encrypted envelope; plaintext is rejected with 400.
└name string
└country string
└encrypted object
└key_id string
└enc_key string
└nonce string
└ciphertext string
└tag string

Response 201

uid string
reference_id string
amount integer
currency string
currency_exponent integer
status created | processing | paid | failed | returned
connector_code string
failure_code string
created_at string<date-time>

Errors

400Invalid parameters
Request
curl -X POST https://api.baton.example/v1/payouts \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
  -H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..." \
  -H "Content-Type: application/json" \
  -d '{
  "reference_id": "PO-10240",
  "amount": 150000,
  "currency": "USD",
  "beneficiary": {
    "name": "Ada Lovelace",
    "country": "US",
    "encrypted": {
      "key_id": "pk_2026q4",
      "enc_key": "base64...",
      "nonce": "base64...",
      "ciphertext": "base64...",
      "tag": "base64..."
    }
  }
}'

Retrieve a payout

GET /v1/payouts/{uid}

Path parameters

uidrequired string

Response 200

uid string
reference_id string
amount integer
currency string
currency_exponent integer
status created | processing | paid | failed | returned
connector_code string
failure_code string
created_at string<date-time>
Request
curl -X GET https://api.baton.example/v1/payouts/{uid} \
  -H "Authorization: Bearer sk_live_xxx"

Cancel a payout

POST /v1/payouts/{uid}/cancel

Only created (awaiting dual approval) can be cancelled. Once submitted to the provider it cannot be recalled — you can only wait for the outcome, and a failure returns the funds to your balance. The earlier you catch a wrong amount, the better.

Path parameters

uidrequired string

Headers

Idempotency-Keyrequired string A unique string you generate (UUID/ULID recommended). Replaying the same key within 24 hours returns the original result and never creates a second payment.

Response 200

uid string
reference_id string
amount integer
currency string
currency_exponent integer
status created | processing | paid | failed | returned
connector_code string
failure_code string
created_at string<date-time>

Errors

409The idempotency key was reused with a different body, or the object's state does not allow this operation
Request
curl -X POST https://api.baton.example/v1/payouts/{uid}/cancel \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
  -H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..."