Skip to main content
POST
Create Payout User

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.

Request Body

string
required
The email address of the payout userFormat: Valid email address Max length: 255 characters
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

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

Example Request

Example Response

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
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.
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.
Returned when payouts are not enabled for your business.How to resolve: Enable payouts in your dashboard 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.

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