Payouts
Brazil (BRL)
How to create BRL payouts
Payouts allow you to send funds from your merchant account to user bank cards, phone numbers, or other payment methods.
Before you start
How to authorize your requests
Before making requests, ensure your merchant account has sufficient funds to create a payout.
Creating a Payout
Send a POST request to create a new payout:
POST /v1/payoutsRequest Example
curl -X POST "https://api.1capital.capital/v1/payouts" \
-H "Content-Type: application/json" \
-H "X-Api-Token: YOUR_API_TOKEN" \
-d '{
"amount": 1000.50,
"currency": "RUB",
"paymentType": "EMAIL",
"account": {
"name": "Ivan Ivanov",
"requisites": "mail@mail.com",
"userId": "user_12345"
},
"note": "Payout for order #1234"
}'Request Parameters
Main Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| amount | number | ✅ Yes | Amount to payout |
| currency | string | ✅ Yes | Currency code |
| paymentType | string | ✅ Yes | Payment type |
| account | object | ✅ Yes | Recipient account details |
| note | string | ❌ No | Note for payout |
| externalId | string | ❌ No | Payout identifier in your system |
| callbackUrl | string | ❌ No | Webhook notification address for the payout |
account Object
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | ✅ Yes | Recipient name |
| requisites | string | ✅ Yes | Account requisites (card number / phone number, depends on payment type) |
| userId | string | ✅ Yes | User ID in your system |
Supported Currencies
| Value | Description |
|---|---|
| BRL | Brazilian Real |
Payment Types
| Value | Description | Example |
|---|---|---|
| RANDOM | Random PIX key | super-uuid-secret |
| SIM | Transfer to phone number | +551113434354545 |
| Transfer to email | email@example.com | |
| CNPJ | Transfer to CNPJ (Brazil) | 12345678000200 |
| CPF | Transfer to CPF (Brazil) | 12345678900 |
Successful Response Example
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"merchantId": "123e4567-e89b-12d3-a456-426614174000",
"amount": "1000.50",
"account": {
"name": "Ivan Ivanov",
"requisites": "4111111111111111",
"userId": "user_12345"
},
"status": "CREATED",
"type": "EMAIL",
"requisites": {},
"statusMessage": null,
"metadata": null,
"callbackUrl": null,
"createdAt": "2023-03-21T12:34:56Z",
"updatedAt": "2023-03-21T12:34:56Z",
"completedAt": null
}Response Fields
| Field | Type | Description |
|---|---|---|
| id | string | Payout UUID |
| merchantId | string | Your merchant UUID |
| amount | string | Payout amount |
| account | object | Recipient account details |
| status | string | Current payout status |
| type | string | Payment type |
| requisites | object | Additional requisites |
| statusMessage | string / null | Status message (if any) |
| metadata | object / null | Additional metadata |
| callbackUrl | string / null | Webhook notification address for this payout (null — merchant settings are used) |
| createdAt | string | Creation timestamp |
| updatedAt | string | Last update timestamp |
| completedAt | string / null | Completion timestamp |
Payout Statuses
| Status | Description |
|---|---|
| CREATED | Payout created |
| PENDING | Payout is being processed |
| COMPLETED | Payout completed successfully |
| FAILED | Payout failed |
| CANCELED | Payout canceled |
| EXPIRED | Payout expired |
Checking Payout Status
To get the current payout status, send a GET request:
GET /v1/payouts/{payoutId}Request Example
curl -X GET "https://api.1capital.capital/v1/payouts/123e4567-e89b-12d3-a456-426614174000" \
-H "X-Api-Token: YOUR_API_TOKEN"Payout status updates are also delivered via webhooks: pass callbackUrl in
the request body or specify it in your merchant settings. Polling the status
by ID may be used as a fallback (for example, every 30 minutes).
Payout Webhooks
Recommendations
- Always verify your merchant balance before creating payouts - Store the
payout
idfrom the response for status tracking - Use webhook notifications (callbackUrl) and verify theX-Signatureheader; polling the status by ID is a fallback - Handle all possible status values in your integration