Skip to content
Payouts
/
/
Initiates a payout to a p...

Overview

Getting started with global payouts.

This platform is designed to help you move money to individuals and businesses across the globe with full transparency and ease.

API Components

To successfully send money, you will interact with:

  1. Payees: Create the profiles of the people or companies you want to pay.
  2. Fees: Calculate the cost of the transaction before you send it.
  3. Payouts: Initiate the actual money transfer and track its progress.

1. Generating Client ID & Client Secret

  • Click Generate Client Credentials
  • A Client ID and Client Secret are generated
  • The Client Secret is displayed only once
  • The Client ID and Client Secret must be stored securely

2. Creating Payees

A Payee is any person or business receiving funds. Think of this as your digital address book.

  • Individual Payees: Only require basic contact information.
  • Business Payees: Require a Tax iD and Phone Number to comply with global financial regulations.

3. Understanding Fees

Before sending money, use the Fees API. This ensures there are no surprises for you or your recipient.

  • Calculation: Fees are based on the destination country, the currency, and the "Rail" (the technical path) the money takes.
  • Preview: We recommend always calling the calculate endpoint before initiating a payout to show your users the final cost.

4. Initiating Payouts

A Payout is the actual movement of money.

Note on Timing: Most payouts are Asynchronous. When you request a payout, we tell you "Accepted." We then work with international banks to move the money. You can track the status using your Unique Reference ID.

5. Glossary of Terms

If you are new to fintech, here are the terms you need to know:

TermSimple Definition
PayeeThe person or business receiving the money.
PayoutThe transaction of sending money from your account to a Payee.
Currency CodeA 3-letter code like USD (US Dollars) or EUR (Euros).
Unique ReferenceA "tracking number" for your payment. Use this to look up a payment's history.
WebhookAn automated notification. We "ping" your system when a payment status changes so you don't have to check manually.
Merchant IDYour specific account number on our platform.
RailThe banking network used to move the money (e.g., SWIFT or ACH).
Download OpenAPI description
payouts.json
payouts.yaml
Languages
Servers
Mock server
https://docs.theropay.co/_mock/theropay/docs/reference/payouts
Sandbox Server (Development)
https://devapi.theropay.co/payouts

Payee

Public APIs for managing payees, including creation, retrieval, update, deletion, and KYC verification.

Operations

Fees

Provides APIs to calculate fees for a transaction. Helps merchants understand applicable charges

Operations

Payout Endpoints

Allows merchants to create, track, list, and cancel payouts to registered payees.

Operations

Initiates a payout to a payee.

Request

The payout is processed asynchronously. Use GET /v1/payouts/{id} to check its status.

Required fields: PayeeId, Amount, Currency.

Optional field: Description.

MerchantId is automatically obtained from the authenticated user.

Security
Bearer
Body

Details of the payout to be created.

payeeIdinteger(int32)required
payeeAccountIdinteger(int32)required
destinationCurrencystring= 3 charactersrequired
amountinteger(int64)>= 1required
notestring or null
curl -i -X POST \
  https://docs.theropay.co/_mock/theropay/docs/reference/payouts/v1/payouts \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "payeeId": 0,
    "payeeAccountId": 0,
    "destinationCurrency": "str",
    "amount": 1,
    "note": "string"
  }'

Responses

Payout created successfully.

Body
payoutUniqueReferencestring or null
payoutIdstring or null
payoutAccountIdstring or null
payeeIdstring
amountnumber(double)
currencyCodestring or null
statestring or null
descriptionstring or null
merchantIdstring or null
paymentDatestring or null(date-time)
payeeDetailsobject(PayeeResponse)
payoutAccountDetailsobject(PayoutAccountResponse)
Response
No response example

Retrieves a list of payouts for a specific payee.

Request

Security
Bearer
Query
payeeIdstringrequired

Payee ID to filter payouts.

curl -i -X GET \
  'https://docs.theropay.co/_mock/theropay/docs/reference/payouts/v1/payouts?payeeId=string' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

List of payouts retrieved successfully.

Body
Array [
payoutUniqueReferencestring or null
payoutIdstring or null
payoutAccountIdstring or null
payeeIdstring
amountnumber(double)
currencyCodestring or null
statestring or null
descriptionstring or null
merchantIdstring or null
paymentDatestring or null(date-time)
payeeDetailsobject(PayeeResponse)
payoutAccountDetailsobject(PayoutAccountResponse)
]
Response
No response example