Executes a previously quoted event, such as a crypto payout.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Overview
Paybis Send API provides a unified endpoint for three operations:
- Crypto Payouts - Send cryptocurrency to a user's wallet
- Fiat Payouts - Send fiat currency (EUR SEPA) to a beneficiary IBAN
- Crypto Pay-ins - Accept cryptocurrency deposits from users
All operations use the same endpoint:
POST /v1/event. The operation type is controlled by the name parameter.
Common Parameters (All Operations):
| Field | Type | Required | Description |
|---|---|---|---|
event_id | UUID | Yes | Unique identifier for idempotency (UUID v4) |
name | String | Yes | Operation name: payment_execute, payout_execute, or pay_in_execute |
timestamp | ISO 8601 | Optional (Deprecated) | Request timestamp in UTC format |
Crypto Payouts (Send Crypto)
Use this mode when you want to send cryptocurrency to a user's wallet. This operation debits your prefunded balance.
- Event Name:
payment_execute - Prerequisite: Requires a valid
quote_idfor a Buy direction (Fiat → Crypto). - Key Action: Validates the quote and immediately broadcasts the transaction to the blockchain.
Request Body (payment_execute)
payment_execute)| Field | Type | Description |
|---|---|---|
payment.transaction.id | String | Your internal transaction ID |
payment.transaction.order_id | String | Order reference for ledger |
payment.transaction.quote_id | UUID | Quote ID from quote generation |
payment.transaction.merchant | String | Merchant/partner name |
payment.transaction.fiat.amount | String (decimal) | Fiat amount (2 decimal places) |
payment.transaction.fiat.currency | String | Fiat currency (USD, EUR, etc.) |
payment.transaction.crypto.amount | String | Crypto amount |
payment.transaction.crypto.currency | String | Crypto currency (ETH, BTC, etc.) |
payment.crypto_destination.crypto_address | String | Recipient's wallet address |
payment.crypto_destination.user.user_id | String | Unique user identifier |
Example Request:
{
"event_id": "19a83b5f-b156-45c8-a7eb-a335c838d362",
"name": "payment_execute",
"payment": {
"transaction": {
"id": "2ffccdce-de70-4d22-872a-b2712c61327c",
"order_id": "order-001",
"quote_id": "b30492f2-07dd-496b-9379-6157a819df9a",
"merchant": "MerchantName",
"fiat": { "amount": "100.00", "currency": "USD" },
"crypto": { "amount": "0.05", "currency": "ETH" }
},
"crypto_destination": {
"type": "constant_user",
"crypto_address": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
"user": { "user_id": "user-001" }
}
}
}Fiat Payouts
Send fiat currency (EUR SEPA) to individual or business beneficiary IBAN.
- Event Name:
payout_execute - Includes: Commission calculation and balance validation
Request
{
"event_id": "3f6c8e92-5a41-4d7b-b2e4-9c1f7a6d8b53",
"name": "payout_execute",
"payout": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"amount": {
"amount": "5",
"currency": "EUR"
},
"beneficiary": {
"type": "business",
"companyName": "Company Name",
"iban": "ES7921000813610123456789"
},
"reference": "Invoice 12345"
}
}Request Fields
| Field | Type | Description |
|---|---|---|
payout.id | UUID | Payout identifier in UUID format. Required. |
payout.amount.amount | String | Payout amount. |
payout.amount.currency | String | Fiat currency code (for example, EUR). |
payout.beneficiary.type | String | individual or business |
payout.beneficiary.iban | String | IBAN (15-34 characters, EUR format) |
payout.beneficiary.firstName | String | First name (individual only, Latin chars) |
payout.beneficiary.lastName | String | Last name (individual only, Latin chars) |
payout.beneficiary.companyName | String | Company name (business only, Latin chars) |
payout.reference | String | Payment reference shown in the bank transfer details. 2 to 140 characters: letters, digits, space and / - ? : ( ) . ' +. Cannot consist of one repeated character (for example 44). Leading and trailing spaces are removed. |
Note: In the request, beneficiary fields use camelCase (firstName, lastName, companyName). The response and Get payout by event ID return them in snake_case (first_name, last_name, company_name).
Note: Paybis matches a saved beneficiary by IBAN, ignoring spaces and letter case. If you send a different beneficiary name for an IBAN that is already saved, the stored name is updated to the new one and used for this payout. No duplicate beneficiary is created.
Commission
Commission is automatically calculated and included:
Commission Amount = Payout Amount × (Commission % / 100)
Total Deduction = Payout Amount + Commission
Example:
- Payout: 100.00 EUR
- Commission %: 2.5%
- Commission: 2.50 EUR
- Total Deduction: 102.50 EUR
Balance Validation
Before submitting a fiat payout:
- Your available balance must be ≥ (payout amount + commission)
- Real-time validation should check:
Available Balance >= Total Deduction - If insufficient balance, show error: "Insufficient balance. Required: 102.50 EUR, Available: 50.00 EUR"
Crypto Pay-ins (Receive Crypto)
Use this mode when you want to accept a crypto deposit from a user. This operation generates a deposit address and prepares your system to credit your ledger upon receipt.
- Event Name:
pay_in_execute - Prerequisite: Requires a valid
quote_idfor a Sell direction (Crypto → Fiat). - Key Action: Locks the sell rate and returns a
blockchain_addresswhere the user must send funds.
Request Body (pay_in_execute)
pay_in_execute)| Field | Type | Description |
|---|---|---|
event_id | UUID | Unique identifier for idempotency. |
name | String | Must be set to pay_in_execute. |
timestamp | Date-Time | Request timestamp. |
pay_in | Object | Container for pay-in details. |
pay_in.id | String | Your internal transaction identifier. |
pay_in.quote_id | UUID | The sell quote ID obtained previously. |
pay_in.fiat | Object | The fiat amount/currency expected (must match quote). |
pay_in.crypto | Object | The crypto amount/currency expected (must match quote). |
Example Request:
{
"event_id": "ce108347-86da-48db-ab13-9a79eb74f315",
"name": "pay_in_execute",
"pay_in": {
"id": "tx-in-001",
"quote_id": "03271efa-7164-4776-88dd-7949beb39010",
"fiat": { "amount": "500.00", "currency": "EUR" },
"crypto": { "amount": "0.015", "currency": "BTC" }
}
}Response
The response format also varies based on the executed event, but always contains a status and result object.
Please note that the blockchain address will be returned only in the webhook or event information (but in some cases it may be null).