Skip to content
Payouts
/
/
Creates a new payee.

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

Creates a new payee.

Request

Use this endpoint to create a new payee.

  • Phone number and Tax ID are optional for individual payee type.
  • Phone number and Tax ID are required for business payee type.
Security
Bearer
Body

Payee creation request payload.

idinteger or null(int32)
payeeTypestringnon-emptyrequired
Example: "INDIVIDUAL|BUSINESS|BRAID"
namestring or null[ 0 .. 100 ] characters
firstNamestring or null[ 0 .. 50 ] characters
lastNamestring or null[ 0 .. 50 ] characters
emailstring or null(email)
phoneNumberstring or null(tel)
taxIdstring or null[ 0 .. 50 ] characters
idTypestring or null[ 0 .. 50 ] characters
dateOfBirthstring or null(date)
addressobject(PayeeAddressRequestDTO)required
address.​addressLinestringnon-emptyrequired
address.​citystringnon-emptyrequired
address.​countrystringnon-emptyrequired
address.​postalCodestringnon-emptyrequired
address.​statestring or null
payeeAccountobject(PayeeAccountRequestDTO)required
payeeAccount.​typestringnon-emptyrequired
payeeAccount.​currencystring or null^[A-Z]{3}$
payeeAccount.​accountTypestring or null
Example: "CHECKINGS|SAVINGS"
payeeAccount.​accountHolderNamestring or null[ 0 .. 100 ] characters
payeeAccount.​bankNamestring or null[ 0 .. 100 ] characters
payeeAccount.​routingNumberstring or null[ 0 .. 20 ] characters
payeeAccount.​accountNumberstring or null[ 0 .. 32 ] characters
payeeAccount.​branchTransitNumberstring or null[ 0 .. 20 ] characters
payeeAccount.​ibanstring or null[ 0 .. 34 ] characters
payeeAccount.​abastring or null[ 0 .. 9 ] characters
payeeAccount.​abaAccountNumberstring or null[ 0 .. 12 ] characters
payeeAccount.​bicstring or null[ 0 .. 11 ] characters
payeeAccount.​bicAccountNumberstring or null[ 0 .. 32 ] characters
payeeAccount.​pixKeyTypestring or null
payeeAccount.​pixKeystring or null[ 0 .. 80 ] characters
curl -i -X POST \
  https://docs.theropay.co/_mock/theropay/docs/reference/payouts/v1/payees/Create \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": 0,
    "payeeType": "INDIVIDUAL|BUSINESS|BRAID",
    "name": "string",
    "firstName": "string",
    "lastName": "string",
    "email": "user@example.com",
    "phoneNumber": "string",
    "taxId": "string",
    "idType": "string",
    "dateOfBirth": "2019-08-24",
    "address": {
      "addressLine": "string",
      "city": "string",
      "country": "string",
      "postalCode": "string",
      "state": "string"
    },
    "payeeAccount": {
      "type": "string",
      "currency": "string",
      "accountType": "CHECKINGS|SAVINGS",
      "accountHolderName": "string",
      "bankName": "string",
      "routingNumber": "string",
      "accountNumber": "string",
      "branchTransitNumber": "string",
      "iban": "string",
      "aba": "string",
      "abaAccountNumber": "string",
      "bic": "string",
      "bicAccountNumber": "string",
      "pixKeyType": "string",
      "pixKey": "string"
    }
  }'

Responses

Payee created successfully.

Body
idinteger(int32)
Example: 174
payeeTypestring or null
Example: "INDIVIDUAL|BUSINESS|BRAID"
namestring or null
emailstring or null
phoneNumberstring or null
taxIdstring or null
businessNamestring or null
Example: "ABC Private ltd"
businessTypestring or null
Example: null
nationalitystring or null
Example: "USA"
idTypestring or null
Example: "SSN"
currencystring or null
Example: "USD"
addressobject(AddressResponseDto)
dateOfBirthstring or null(date)
isActiveboolean
Response
No response example

Retrieves a payee by ID.

Request

Security
Bearer
Path
idinteger(int32)required

Unique identifier of the payee.

curl -i -X GET \
  'https://docs.theropay.co/_mock/theropay/docs/reference/payouts/v1/payees/{id}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Payee retrieved successfully.

Body
idinteger(int32)
Example: 174
payeeTypestring or null
Example: "INDIVIDUAL|BUSINESS|BRAID"
namestring or null
emailstring or null
phoneNumberstring or null
taxIdstring or null
businessNamestring or null
Example: "ABC Private ltd"
businessTypestring or null
Example: null
nationalitystring or null
Example: "USA"
idTypestring or null
Example: "SSN"
currencystring or null
Example: "USD"
addressobject(AddressResponseDto)
dateOfBirthstring or null(date)
isActiveboolean
Response
No response example

Lists all payees.

Request

Lists all payees with optional pagination and sorting.

Security
Bearer
Body
pageNumberinteger(int32)
pageSizeinteger(int32)
routestring or null
sortPropertystring or null
isDescendingboolean
merchantIdinteger or null(int32)
searchTextstring or null
curl -i -X POST \
  https://docs.theropay.co/_mock/theropay/docs/reference/payouts/v1/payees/list \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "pageNumber": 0,
    "pageSize": 0,
    "route": "string",
    "sortProperty": "string",
    "isDescending": true,
    "merchantId": 0,
    "searchText": "string"
  }'

Responses

List of payees retrieved successfully.

Body
Array [
idinteger(int32)
Example: 174
payeeTypestring or null
Example: "INDIVIDUAL|BUSINESS|BRAID"
namestring or null
emailstring or null
phoneNumberstring or null
taxIdstring or null
businessNamestring or null
Example: "ABC Private ltd"
businessTypestring or null
Example: null
nationalitystring or null
Example: "USA"
idTypestring or null
Example: "SSN"
currencystring or null
Example: "USD"
addressobject(AddressResponseDto)
dateOfBirthstring or null(date)
isActiveboolean
]
Response
No response example

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