Skip to main content
POST
/
payout
/
create
Create Payout User
curl --request POST \
  --url https://api.payviox.com/payout/create \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "<string>",
  "amount": 123
}
'
{
  "hash": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6"
}

​
Overview

Creates a new payout user or adds funds to an existing payout user. The amount is automatically debited from your business payout balance and allocated to the user.
Payouts must be enabled for your business in the dashboard settings before using this endpoint.
This endpoint requires a secure API key. Ensure you have sufficient payout balance before calling this endpoint.

​
Authentication

This endpoint requires API key authentication. See Payout API Authentication for details. 
Authorization: Bearer YOUR_API_KEY

​
Request Body

​
email
string
required
The email address of the payout userFormat: Valid email address Max length: 255 characters
​
amount
integer
required
The amount to allocate to the payout user in cents (e.g., 10000 = $100.00)Minimum: 1 cent Maximum: 100,000,000 cents (equivalent to $1,000,000.00)

​
Response

​
hash
string
Unique hash generated for the payout user. This hash can be used to retrieve payout information later.

​
Example Request

curl https://api.payviox.com/payout/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "email": "user@example.com",
    "amount": 10000
  }'

​
Example Response

{
  "hash": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6"
}

​
Error Responses

Returned when request body fields are missing or invalid. The response contains an object where each key is a field name and the value is an array of error messages.Common causes:
  • email is missing or not a valid email format
  • amount is missing, not an integer, less than 1, or exceeds the maximum
{
  "email": ["The email must be a valid email address."],
  "amount": ["The amount must be at least 1."]
}
Returned when your business payout balance is too low to cover the requested amount.How to resolve: Check your payout balance using the Get Balance endpoint before creating payout users, or add funds via the dashboard.
{
  "error": "Insufficient payout balance"
}
Returned when the API key is missing or invalid.How to resolve: Ensure you are sending a valid Secret API Key in the Authorization: Bearer header.
{
  "error": "Unauthorized"
}
Returned when payouts are not enabled for your business.How to resolve: Enable payouts in your dashboard settings.
{
  "error": "Payouts are currently disabled. Please enable them in Settings."
}
Returned when an unexpected error occurs on the server. No funds are debited if this error occurs.How to resolve: Retry the request. If the error persists, contact support.
{
  "error": "Internal server error"
}

​
How It Works

​
Transaction Safety

This endpoint uses transactional operations to ensure data consistency:
  1. Business Balance Debit: The amount is debited from your business payout balance. If insufficient funds exist, the operation fails immediately.
  2. User Creation/Update: The payout user is created (if new) or updated (if existing) with the amount added to their balance.
  3. Transaction History: A history record is created to track the transaction.

​
User Creation vs Update

  • New User: If the email doesn’t exist for your business, a new payout user is created with the specified amount.
  • Existing User: If the email already exists, the amount is added to their existing balance.

​
Hash Generation

Each payout user receives a unique hash. This hash:
  • Can be used to retrieve payout information
  • Is generated server-side
  • Can be used for hash-based authentication (see Authentication)

​
Validation Rules

  • Must be a valid email format
  • Maximum 255 characters
  • Case-insensitive (duplicate emails are treated as the same user)
  • Must be a positive integer
  • Minimum: 1 cent
  • Maximum: 100,000,000 cents ($1,000,000.00)
  • Amount is specified in cents (smallest currency unit)
  • Your business must have sufficient payout balance to cover the amount
  • The balance check and debit happen in a single transaction
  • If balance is insufficient, the operation fails without creating the user
  • Payouts must be enabled for your business in dashboard settings
  • If disabled, the endpoint returns a 403 error
  • Check payout status before attempting to create users

​
Use Cases

Reward Distribution

Distribute rewards or commissions to users based on their email address

Refund Processing

Process refunds by adding funds to user payout accounts

Affiliate Payments

Pay affiliates by creating payout users and allocating their earnings

Balance Management

Manage user balances by adding funds incrementally over time

​
Best Practices

Check Balance First: Before creating payout users, verify your business has sufficient payout_balance to avoid failed requests.
Not idempotent: Calling this endpoint multiple times with the same email will add the amount each time. Ensure you don’t accidentally duplicate allocations.
Error Handling: Always handle the insufficient balance error gracefully and inform users when funds are not available.
Concurrent Requests: Concurrent requests for the same user are safe. However, ensure your business balance can cover all concurrent allocations.

​
Next Steps

Payout Authentication

Learn about hash-based authentication for payout users

Dashboard

Monitor your payout balance and users in the dashboard

Enable Payouts

Enable payouts in your business settings

API Playground

Test API calls directly from your browser