Third-Party Integrations
Payouts
How to create 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.riopay.online/v1/payouts" \
-H "Content-Type: application/json" \
-H "X-Api-Token: YOUR_API_TOKEN" \
-d '{
"amount": 1000.50,
"currency": "RUB",
"paymentType": "C2C",
"account": {
"name": "Ivan Ivanov",
"requisites": "4111111111111111",
"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 |
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 |
|---|---|
| C2C | Card-to-Card transfer |
| SIM | Transfer to phone number |
| Transfer to email | |
| CNPJ | Transfer to CNPJ (Brazil) |
| CPF | Transfer to CPF (Brazil) |
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": "C2C",
"requisites": {},
"statusMessage": null,
"metadata": 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 |
| 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.riopay.online/v1/payouts/123e4567-e89b-12d3-a456-426614174000" \
-H "X-Api-Token: YOUR_API_TOKEN"There are no webhooks for payouts. To get payout status updates, you need to poll the status by ID periodically (e.g., every 30 minutes).
Recommendations
- Always verify your merchant balance before creating payouts
- Store the payout
idfrom the response for status tracking - Implement periodic status polling for payout updates
- Handle all possible status values in your integration