Create payout

Quick Reference

WhatSend an outbound payment (payout) funded by a wallet

WhyPay suppliers, partners, and customers across LATAM through a single unified endpoint

Reading Time10 min

DifficultyIntermediate

PrerequisitesAuthentication → A funded wallet → A registered merchant (when required by your account)

POST/api/v1/bank/wallet/payout/Bearer TokenCreate a payout debiting a wallet

How payouts work

A payout is the outbound flow — money leaving the platform, the inverse of a charge. A single endpoint handles every payment rail; the type_payout field selects which one, and each type requires its matching destination object.

Payout flow

Payout statuses

Status	Meaning	Terminal?
`pending`	Created, awaiting processing	No
`issued`	Sent to the provider	No
`realized`	Confirmed and settled	Yes
`returned`	Returned by the receiving bank	Yes
`canceled`	Canceled	Yes
`error`	Failed during processing	Yes
`expired`	Expired	Yes

Request headers

Header	Value	Required
`Authorization`	`Bearer {A55_ACCESS_TOKEN}`	Yes
`Content-Type`	`application/json`	Yes

Request body

Field	Type	Required	Description
`wallet_uuid`	string (UUID)	Yes	Wallet that will fund the payout
`type_payout`	string	Yes	Payment rail: `pix`, `bank_transfer`, `ted`, `spei`, `cash_pickup`
`value`	number (float)	Yes	Amount to send. Must be greater than zero
`description`	string	Yes	Free-text description of the payout
`currency`	string	No	ISO 4217 code. Defaults to the wallet currency when omitted
`merchant_id`	string (UUID)	No	Merchant the payout belongs to. Required when your account is configured with merchants
`transaction_reference`	string	No	External idempotency key (scoped to the wallet). A UUID is generated when omitted
`schedule_date`	string	No	`YYYY-MM-DD` to schedule the payout
`country_code`	string	No	ISO 3166-1 alpha-2 of the destination
`providers`	string[]	No	Provider UUIDs to force routing to specific providers
`webhook_url`	string (URL)	No	URL notified on status changes
`pix_destination`	object	Conditional	Required when `type_payout` is `pix`
`bank_destination`	object	Conditional	Required when `type_payout` is `bank_transfer`, `ted`, or `spei`
`cash_destination`	object	Conditional	Required when `type_payout` is `cash_pickup`

`pix_destination`

Field	Type	Required	Description
`pix_address_key`	string	Yes	PIX key value
`pix_address_key_type`	string	Yes	PIX key type (`cpf`, `cnpj`, `email`, `phone`, `evp`)
`beneficiary_name`	string	No	Beneficiary full name
`beneficiary_tax_id`	string	No	Beneficiary CPF/CNPJ. Required for email/phone/evp keys; optional for cpf/cnpj keys (uses the key as document)

`bank_destination` (bank_transfer / ted / spei)

Field	Type	Required	Description
`country_code`	string	Yes	ISO-3166 alpha-2 or alpha-3
`beneficiary_name`	string	Yes	Beneficiary first name
`beneficiary_last_name`	string	Yes	Beneficiary last name
`document_type`	string	Yes	Beneficiary document type: `CPF`, `CNPJ`, `DNI`, `CUIT`, `CUIL`, `CURP`, `RFC`, `INE`, `PAS`
`beneficiary_tax_id`	string	Yes	Beneficiary document number
`account_number`	string	Conditional	Account number, CBU/CVU, CCI, CLABE, etc. Required unless `bank_alias` is used
`bank_alias`	string	Conditional	Argentina CBU alias (6-20 chars). Alternative to `account_number`
`bank_code`	string	No	Provider bank code. Brazil TED: 8-digit ISPB or COMPE (e.g. `001`)
`account_type`	string	No	Savings / Current / Cash / RUT / etc. (varies by country)
`account_agency`	string	No	Bank branch/agency (Brazil TED)
`bank_name`	string	No	Bank name
`beneficiary_email`	string	No	Required when `account_type` is `Cash`
`beneficiary_phone`	string	No	Beneficiary phone
`expiration_date`	string	No	`YYYY-MM-DD` (cash networks)

`cash_destination` (cash_pickup)

Field	Type	Required	Description
`country_code`	string	Yes	Destination country
`bank_code`	string	Yes	Cash network code (e.g. `010`, `456`)
`beneficiary_name`	string	Yes	Beneficiary name
`beneficiary_email`	string	Yes	The pickup code is sent to this email
`document_type`	string	Yes	Beneficiary document type: `CPF`, `CNPJ`, `DNI`, `CUIT`, `CUIL`, `CURP`, `RFC`, `INE`, `PAS`
`beneficiary_tax_id`	string	Yes	Beneficiary document number
`beneficiary_last_name`	string	No	Beneficiary last name
`beneficiary_phone`	string	No	Beneficiary phone
`expiration_date`	string	No	`YYYY-MM-DD` pickup expiration

Response fields

Field	Type	Description
`payout_uuid`	string	Internal payout identifier
`external_id`	string	Provider's payout id
`status`	string	Current payout status (see table above)
`type_payout`	string	Payout rail used
`amount`	number (float)	Payout amount
`fee`	number (float)	Provider fee
`currency`	string	ISO 4217 currency
`description`	string	Payout description
`country_code`	string	Destination country
`beneficiary_name`	string	Beneficiary name
`transaction_reference`	string	Idempotency key used
`submitted_date`	string	Date sent to the provider
`confirmed_date`	string	Date confirmed
`schedule_date`	string	Scheduled date, when applicable
`payment_code`	string	Cash pickup code (cash payouts only)
`authorization_code`	string	Provider authorization code, when available
`authorization_date`	string	Authorization date, when available
`transaction_id`	string	Provider transaction id, when available
`destination`	object	Echo of the destination data
`message`	array	Provider/processing messages
`created`	string	ISO 8601 creation timestamp
`updated`	string	ISO 8601 last update timestamp

Error responses

Status	Code	Description
400	`errors.payout.validate_error`	Payload failed validation (missing `type_payout`, `value <= 0`, missing destination fields, etc.)
400	`errors.payout.destination_invalid`	Destination object is invalid for the chosen `type_payout`
400	`errors.payout.provider_not_valid`	No eligible provider for this payout
400	`errors.wallet.payout_already_exists`	A payout with the same `transaction_reference` already exists for this wallet
400	`errors.wallet.daily_transaction_limit_exceeded`	The wallet daily limit would be exceeded
400	`errors.wallet.merchant_invalid`	The merchant does not belong to the wallet's account
401	`unauthorized`	Invalid or expired Bearer token
404	`errors.wallet.not_found`	Wallet not found
404	`errors.payout.merchant_not_found`	Merchant not found
422	`errors.payout.insufficient_balance`	The wallet balance is insufficient for this payout

Code examples

PIX out (Brazil)

cURL
Python
Node.js

curl -s -X POST "https://sandbox.api.a55.tech/api/v1/bank/wallet/payout/" \
  -H "Authorization: Bearer $A55_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "type_payout": "pix",
    "value": 100.00,
    "currency": "BRL",
    "description": "Supplier payment #2048",
    "transaction_reference": "PAY-2048",
    "webhook_url": "https://your-app.com/webhooks/a55/payouts",
    "pix_destination": {
      "pix_address_key": "joao@example.com",
      "pix_address_key_type": "email",
      "beneficiary_name": "João Silva",
      "beneficiary_tax_id": "12345678901"
    }
  }'

import requests
import os

token = os.environ["A55_ACCESS_TOKEN"]
base = os.environ.get("A55_API_URL", "https://sandbox.api.a55.tech")

response = requests.post(
    f"{base}/api/v1/bank/wallet/payout/",
    json={
        "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "type_payout": "pix",
        "value": 100.00,
        "currency": "BRL",
        "description": "Supplier payment #2048",
        "transaction_reference": "PAY-2048",
        "webhook_url": "https://your-app.com/webhooks/a55/payouts",
        "pix_destination": {
            "pix_address_key": "joao@example.com",
            "pix_address_key_type": "email",
            "beneficiary_name": "João Silva",
            "beneficiary_tax_id": "12345678901",
        },
    },
    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
)
payout = response.json()
print(f"Payout {payout['payout_uuid']} — status: {payout['status']}")

const token = process.env.A55_ACCESS_TOKEN;
const base = process.env.A55_API_URL || "https://sandbox.api.a55.tech";

const payout = await fetch(`${base}/api/v1/bank/wallet/payout/`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    wallet_uuid: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    type_payout: "pix",
    value: 100.0,
    currency: "BRL",
    description: "Supplier payment #2048",
    transaction_reference: "PAY-2048",
    webhook_url: "https://your-app.com/webhooks/a55/payouts",
    pix_destination: {
      pix_address_key: "joao@example.com",
      pix_address_key_type: "email",
      beneficiary_name: "João Silva",
      beneficiary_tax_id: "12345678901",
    },
  }),
}).then((r) => r.json());

console.log(`Payout ${payout.payout_uuid} — status: ${payout.status}`);

TED (Brazil)

curl -s -X POST "https://sandbox.api.a55.tech/api/v1/bank/wallet/payout/" \
  -H "Authorization: Bearer $A55_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "type_payout": "ted",
    "value": 500.00,
    "currency": "BRL",
    "description": "Vendor settlement",
    "transaction_reference": "PAY-2049",
    "bank_destination": {
      "country_code": "BR",
      "bank_code": "341",
      "account_type": "checking",
      "account_number": "12345-6",
      "account_agency": "0001",
      "bank_name": "Itaú",
      "beneficiary_name": "Maria",
      "beneficiary_last_name": "Costa",
      "document_type": "CPF",
      "beneficiary_tax_id": "98765432100"
    }
  }'

SPEI (Mexico)

curl -s -X POST "https://sandbox.api.a55.tech/api/v1/bank/wallet/payout/" \
  -H "Authorization: Bearer $A55_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "type_payout": "spei",
    "value": 1500.00,
    "currency": "MXN",
    "description": "Payout MXN",
    "transaction_reference": "PAY-2050",
    "bank_destination": {
      "country_code": "MX",
      "account_number": "012180012345678901",
      "beneficiary_name": "Carlos",
      "beneficiary_last_name": "Hernández",
      "document_type": "RFC",
      "beneficiary_tax_id": "HEGC800101XXX"
    }
  }'

Bank transfer (LATAM)

curl -s -X POST "https://sandbox.api.a55.tech/api/v1/bank/wallet/payout/" \
  -H "Authorization: Bearer $A55_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "type_payout": "bank_transfer",
    "value": 250.00,
    "currency": "ARS",
    "description": "Payout Argentina",
    "transaction_reference": "PAY-2051",
    "bank_destination": {
      "country_code": "AR",
      "bank_alias": "mi.alias.cbu",
      "beneficiary_name": "Lucía",
      "beneficiary_last_name": "Gómez",
      "document_type": "DNI",
      "beneficiary_tax_id": "20304050607"
    }
  }'

Cash pickup (Ecuador)

curl -s -X POST "https://sandbox.api.a55.tech/api/v1/bank/wallet/payout/" \
  -H "Authorization: Bearer $A55_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "type_payout": "cash_pickup",
    "value": 200.00,
    "currency": "USD",
    "description": "Cash pickup payout",
    "transaction_reference": "PAY-2052",
    "cash_destination": {
      "country_code": "EC",
      "bank_code": "456",
      "beneficiary_name": "Pedro",
      "beneficiary_email": "pedro@example.com",
      "document_type": "Cedula",
      "beneficiary_tax_id": "1234567890"
    }
  }'

Complete response example

PIX payout accepted

{
  "payout_uuid": "9b1f0c88-3a3c-4f2f-9d6e-1f0a2d4e88c1",
  "external_id": "MN-20260616-0001",
  "status": "issued",
  "type_payout": "pix",
  "amount": 100.00,
  "fee": 0.50,
  "currency": "BRL",
  "description": "Supplier payment #2048",
  "country_code": "BR",
  "beneficiary_name": "João Silva",
  "transaction_reference": "PAY-2048",
  "submitted_date": "2026-06-16",
  "confirmed_date": null,
  "schedule_date": null,
  "destination": {
    "pix_address_key": "joao@example.com",
    "pix_address_key_type": "email"
  },
  "message": [],
  "created": "2026-06-16T18:00:00Z",
  "updated": "2026-06-16T18:00:00Z"
}

Cash pickup accepted (includes pickup code)

{
  "payout_uuid": "5c2a13f0-5e74-4b21-9c6a-2bd9d9b0aa10",
  "external_id": "MN-20260616-0002",
  "status": "issued",
  "type_payout": "cash_pickup",
  "amount": 200.00,
  "fee": 1.20,
  "currency": "USD",
  "description": "Cash pickup payout",
  "country_code": "EC",
  "beneficiary_name": "Pedro",
  "transaction_reference": "PAY-2052",
  "payment_code": "EC-PICKUP-7788",
  "message": [],
  "created": "2026-06-16T18:05:00Z",
  "updated": "2026-06-16T18:05:00Z"
}

Always confirm via webhook

The synchronous response returns the initial status. A payout typically moves from issued to realized asynchronously. Set webhook_url and treat the webhook as the source of truth for the final outcome. See Payout webhook.

Get payout →Retrieve the current status and details of a payout.List payouts →List and filter the payouts of a wallet.Payout webhook →Receive a notification when the payout status changes.

Quick Reference

How payouts work​

Payout flow​

Payout statuses​

Request headers​

Request body​

pix_destination​

bank_destination (bank_transfer / ted / spei)​

cash_destination (cash_pickup)​

Response fields​

Error responses​

Code examples​

PIX out (Brazil)​

TED (Brazil)​

SPEI (Mexico)​

Bank transfer (LATAM)​

Cash pickup (Ecuador)​

Complete response example​

PIX payout accepted​

Cash pickup accepted (includes pickup code)​