API Reference

Payout API

Complete API reference for sending money to beneficiaries via PIX, SPEI, bank transfers, and more.

Endpoints

POST/api/v1/payout

Create payout

GET/api/v1/payout/{payout_id}

Get payout status

POST/api/v1/payout/{payout_id}/cancel

Cancel payout

GET/api/v1/payout

List payouts

GET/api/v1/payout/methods/available

Get available payout methods

POST/api/v1/payout/validate-beneficiary

Validate beneficiary

Create Payout

POST/api/v1/payout

Creates a new payout to send money to a beneficiary.

Headers

Header	Required	Description
`X-API-Key`	Yes	Your API key
`Content-Type`	Yes	application/json

Request Body

Field	Type	Required	Description
`method_code`	string	Yes	Payout method code (e.g., "s-interio-mt-5")
`amount`	number	Yes	Payout amount (must be greater than 0)
`currency`	string	Yes	ISO 4217 currency code (BRL, PEN, MXN, ARS, COP)
`beneficiary`	object	Yes	Beneficiary information (see below)
`description`	string	No	Description of the payout
`notification_url`	string	No	Webhook URL for payout notifications
`metadata`	object	No	Custom key-value pairs returned in webhooks

Beneficiary Object

The beneficiary object contains the recipient's information:

Field	Type	Required	Description
`name`	string	Yes	Beneficiary full name
`document`	string	Yes	Document number (CPF, CNPJ, DNI, etc.)
`document_type`	string	Yes	Document type: CPF, CNPJ, DNI, RUT, CURP, CC, CE, RUC
`instant_transfer_key`	string	Conditional	PIX key, CLABE, CVU, or CBU (required for instant transfers)
`instant_transfer_type`	string	Conditional	Key type: email, cpf, phone, random, clabe, cvu, cbu
`bank_code`	string	Conditional	Bank code (required for traditional bank transfers)
`account_number`	string	Conditional	Bank account number
`account_type`	string	Conditional	Account type: checking, savings
`wallet_id`	string	Conditional	Wallet identifier (for wallet payouts)

Field Requirements

The required fields depend on the payout method. PIX payouts require instant_transfer_key and instant_transfer_type. Traditional bank transfers require bank_code, account_number, and account_type.

Example Request

create-payout.sh

curl -X POST "https://cashier.flowpayment.net/api/v1/payout" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_live_your_api_key" \
  -d '{
    "method_code": "s-interio-mt-5",
    "amount": 1000.00,
    "currency": "BRL",
    "beneficiary": {
      "name": "Joao Silva",
      "document": "12345678909",
      "document_type": "CPF",
      "instant_transfer_key": "joao@email.com",
      "instant_transfer_type": "email"
    },
    "description": "Commission payment",
    "notification_url": "https://your-site.com/webhooks/payout"
  }'

Success Response (200)

success-response.json

{
  "success": true,
  "payout_id": "po_abc123xyz",
  "status": "processing",
  "provider_reference": "sfp_tx_123",
  "created_at": "2026-01-13T12:00:00Z",
  "message": "Payout is being processed"
}

Error Response (4xx)

error-response.json

{
  "success": false,
  "error": {
    "code": "INVALID_BENEFICIARY",
    "message": "Invalid PIX key format"
  }
}

Payout Method Codes

Use these method codes based on the destination country:

Method Code	Type	Country	Currency
`s-interio-mt-5`	PIX Payout	Brazil (BRA)	BRL
`s-interio-mt-6`	Bank Transfer	Peru (PER)	PEN
`s-interio-mt-30`	SPEI	Mexico (MEX)	MXN
`s-interio-mt-31`	CVU/CBU	Argentina (ARG)	ARS
`s-interio-mt-32`	Bank Transfer	Colombia (COL)	COP

Country-Specific Examples

Brazil - PIX Payout

pix-payout.json

{
  "method_code": "s-interio-mt-5",
  "amount": 500.00,
  "currency": "BRL",
  "beneficiary": {
    "name": "Maria Santos",
    "document": "12345678909",
    "document_type": "CPF",
    "instant_transfer_key": "12345678909",
    "instant_transfer_type": "cpf"
  },
  "description": "Refund #1234"
}

PIX Key Types

Brazil supports multiple PIX key types: email, cpf, cnpj, phone, and random (EVP).

Mexico - SPEI Payout

spei-payout.json

{
  "method_code": "s-interio-mt-30",
  "amount": 2500.00,
  "currency": "MXN",
  "beneficiary": {
    "name": "Carlos Hernandez",
    "document": "HECA850101HDFRRL09",
    "document_type": "CURP",
    "instant_transfer_key": "012345678901234567",
    "instant_transfer_type": "clabe"
  },
  "description": "Salary payment"
}

CLABE Format

CLABE (Clave Bancaria Estandarizada) is an 18-digit bank account number used in Mexico. It includes the bank code, branch, account number, and a check digit.

Argentina - CVU/CBU Payout

argentina-payout.json

{
  "method_code": "s-interio-mt-31",
  "amount": 15000.00,
  "currency": "ARS",
  "beneficiary": {
    "name": "Pablo Rodriguez",
    "document": "20123456789",
    "document_type": "DNI",
    "instant_transfer_key": "0000003100010000000001",
    "instant_transfer_type": "cvu"
  },
  "description": "Service payment"
}

CVU vs CBU

CBU (22 digits) is for traditional bank accounts. CVU (22 digits) is for virtual wallets like MercadoPago. Both use the same format.

Get Payout Status

GET/api/v1/payout/{payout_id}

Retrieves the current status and details of a payout.

Example Request

bash

curl -X GET "https://cashier.flowpayment.net/api/v1/payout/po_abc123xyz" \
  -H "X-API-Key: sk_live_your_api_key"

Success Response

payout-details.json

{
  "payout_id": "po_abc123xyz",
  "status": "completed",
  "amount": 1000.00,
  "currency": "BRL",
  "method_code": "s-interio-mt-5",
  "beneficiary": {
    "name": "Joao Silva",
    "document": "***456***",
    "instant_transfer_key": "j***@email.com"
  },
  "provider_reference": "sfp_tx_123",
  "description": "Commission payment",
  "created_at": "2026-01-13T12:00:00Z",
  "completed_at": "2026-01-13T12:01:30Z"
}

Cancel Payout

POST/api/v1/payout/{payout_id}/cancel

Cancels a pending payout. Cannot cancel payouts already processing or completed.

Example Request

bash

curl -X POST "https://cashier.flowpayment.net/api/v1/payout/po_abc123xyz/cancel" \
  -H "X-API-Key: sk_live_your_api_key"

Success Response

json

{
  "success": true,
  "payout_id": "po_abc123xyz",
  "status": "cancelled",
  "message": "Payout cancelled successfully"
}

Cancellation Window

Payouts can only be cancelled while in pending status. Once a payout moves to processing, it cannot be cancelled.

List Payouts

GET/api/v1/payout

Lists all payouts for your merchant account with pagination and filtering.

Query Parameters

Parameter	Type	Description
`status`	string	Filter by status (pending, processing, completed, failed, cancelled)
`from_date`	string	Start date (ISO 8601 format)
`to_date`	string	End date (ISO 8601 format)
`limit`	number	Number of records (default: 20, max: 100)
`offset`	number	Number of records to skip

Example Request

bash

curl -X GET "https://cashier.flowpayment.net/api/v1/payout?status=completed&limit=10" \
  -H "X-API-Key: sk_live_your_api_key"

Success Response

list-response.json

{
  "success": true,
  "data": [
    {
      "payout_id": "po_abc123xyz",
      "status": "completed",
      "amount": 1000.00,
      "currency": "BRL",
      "beneficiary_name": "Joao Silva",
      "created_at": "2026-01-13T12:00:00Z"
    }
  ],
  "pagination": {
    "total": 45,
    "limit": 10,
    "offset": 0
  }
}

Get Available Payout Methods

GET/api/v1/payout/methods/available

Returns the payout methods available for your merchant account.

Query Parameters

Parameter	Type	Description
`country`	string	Filter by country code (BRA, MEX, ARG, PER, COL)
`currency`	string	Filter by currency code (BRL, MXN, ARS, PEN, COP)

Example Request

bash

curl -X GET "https://cashier.flowpayment.net/api/v1/payout/methods/available?country=BRA" \
  -H "X-API-Key: sk_live_your_api_key"

Success Response

methods-response.json

{
  "success": true,
  "methods": [
    {
      "method_code": "s-interio-mt-5",
      "name": "PIX Payout",
      "type": "instant_transfer",
      "country": "BRA",
      "currency": "BRL",
      "min_amount": 1.00,
      "max_amount": 100000.00,
      "required_fields": ["name", "document", "document_type", "instant_transfer_key", "instant_transfer_type"]
    }
  ]
}

Validate Beneficiary

POST/api/v1/payout/validate-beneficiary

Validates beneficiary information before creating a payout.

Example Request

validate-beneficiary.sh

curl -X POST "https://cashier.flowpayment.net/api/v1/payout/validate-beneficiary" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_live_your_api_key" \
  -d '{
    "method_code": "s-interio-mt-5",
    "beneficiary": {
      "name": "Joao Silva",
      "document": "12345678909",
      "document_type": "CPF",
      "instant_transfer_key": "joao@email.com",
      "instant_transfer_type": "email"
    }
  }'

Success Response

json

{
  "success": true,
  "valid": true,
  "beneficiary": {
    "name": "Joao Silva",
    "document_valid": true,
    "key_valid": true
  }
}

Validation Error Response

json

{
  "success": true,
  "valid": false,
  "errors": [
    {
      "field": "document",
      "message": "Invalid CPF format"
    }
  ]
}

Payout Status

pending

Payout created, waiting to be processed

processing

Payout is being processed by the provider

completed

Payout successfully delivered to beneficiary

failed

Payout failed (invalid account, insufficient funds, etc.)

cancelled

Payout was cancelled before processing

refunded

Payout was returned by the beneficiary bank

Webhooks

When a payout status changes, we send a webhook notification to your notification_url:

Webhook Events

Event	Description
`payout.processing`	Payout has started processing
`payout.completed`	Payout was successfully delivered
`payout.failed`	Payout failed
`payout.refunded`	Payout was returned

Webhook Payload

webhook-payload.json

{
  "event": "payout.completed",
  "payout_id": "po_abc123xyz",
  "status": "completed",
  "amount": 1000.00,
  "currency": "BRL",
  "beneficiary_name": "Joao Silva",
  "provider_reference": "sfp_tx_123",
  "completed_at": "2026-01-13T12:01:30Z",
  "metadata": {
    "your_reference": "payout_001"
  }
}

Webhook Security

Verify webhook authenticity by checking the X-Webhook-Signature header. Compare it with an HMAC-SHA256 of the payload using your webhook secret.

Error Codes

Code	HTTP	Description
`UNAUTHORIZED`	`401`	Invalid or missing API key
`VALIDATION_ERROR`	`400`	Invalid request parameters
`INVALID_BENEFICIARY`	`400`	Invalid beneficiary information
`INSUFFICIENT_BALANCE`	`400`	Merchant balance insufficient for payout
`METHOD_NOT_AVAILABLE`	`400`	Payout method not available for merchant
`PAYOUT_NOT_FOUND`	`404`	Payout ID not found
`CANNOT_CANCEL`	`409`	Payout cannot be cancelled (already processing)
`AMOUNT_LIMIT_EXCEEDED`	`400`	Amount exceeds allowed limit for method
`RATE_LIMIT_EXCEEDED`	`429`	Too many requests

Idempotency

To prevent duplicate payouts, include an X-Idempotency-Key header:

bash

curl -X POST "https://cashier.flowpayment.net/api/v1/payout" \
  -H "X-API-Key: your_api_key" \
  -H "X-Idempotency-Key: unique_payout_id_12345" \
  -d '{ ... }'

Important

Always use idempotency keys for payout requests. If a network error occurs, you can safely retry the request without risking duplicate payouts.

Rate Limits

Endpoint	Limit
`POST /api/v1/payout`	50 requests/minute
`GET /api/v1/payout/{id}`	200 requests/minute
`GET /api/v1/payout`	100 requests/minute
`POST /api/v1/payout/validate-beneficiary`	100 requests/minute

Testing

Use sandbox mode for testing payouts without real money transfers.

Sandbox Mode

In sandbox mode, payouts are simulated. Use test beneficiary data provided in your dashboard to test different scenarios (success, failure, etc.).

Test Beneficiary Data

Document	Result
`00000000191`	Payout succeeds
`00000000272`	Payout fails (invalid account)
`00000000353`	Payout refunded