Skip to main content
POST
https://api.payviox.com
/
payout
/
create
Create Payout User
curl --request POST \
  --url https://api.payviox.com/payout/create \
  --header 'Authorization: Bearer <token>' \
  --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. This endpoint uses atomic operations to prevent race conditions and ensure data consistency.
Payouts must be enabled for your business in the dashboard settings before using this endpoint.
This endpoint requires a secure API key. The operation debits your business payout balance atomically, so ensure you have sufficient funds 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
SHA256 HMAC 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": "[email protected]",
    "amount": 10000
  }'

​
Example Response

{
  "hash": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6"
}

​
Error Responses

{
  "email": [
    "The email field is required."
  ],
  "amount": [
    "The amount field is required."
  ]
}

​
How It Works

​
Atomic Operations

This endpoint uses MongoDB atomic operations to ensure data consistency:
  1. Business Balance Debit: The amount is atomically 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 SHA256 HMAC hash based on their email address. This hash:
  • Remains consistent for the same email address
  • Can be used to retrieve payout information
  • Is generated server-side using a secure secret
  • 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 are atomic (prevents race conditions)
  • 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.
Idempotency: This endpoint is idempotent for existing users - calling it 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: The endpoint uses atomic operations, so 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