# 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:

| Term | Simple Definition |
| :--- | :--- |
| **Payee** | The person or business receiving the money. |
| **Payout** | The transaction of sending money from your account to a Payee. |
| **Currency Code** | A 3-letter code like `USD` (US Dollars) or `EUR` (Euros). |
| **Unique Reference** | A "tracking number" for your payment. Use this to look up a payment's history. |
| **Webhook** | An automated notification. We "ping" your system when a payment status changes so you don't have to check manually. |
| **Merchant ID** | Your specific account number on our platform. |
| **Rail** | The banking network used to move the money (e.g., SWIFT or ACH). |

---



## Servers

Sandbox Server (Development)
```
https://devapi.theropay.co/payouts
```

## Security

### Bearer

JWT Authorization header using the Bearer scheme.

Type: http
Scheme: bearer
Bearer Format: JWT

## Download OpenAPI description

[Overview](https://docs.theropay.co/_bundle/Theropay/docs/reference/payouts.yaml)

## Payee

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

### Creates a new payee.

 - [POST /v1/payees/Create](https://docs.theropay.co/theropay/docs/reference/payouts/payee/paths/~1v1~1payees~1create/post.md): 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.

### Retrieves a payee by ID.

 - [GET /v1/payees/{id}](https://docs.theropay.co/theropay/docs/reference/payouts/payee/paths/~1v1~1payees~1%7Bid%7D/get.md)

### Lists all payees.

 - [POST /v1/payees/list](https://docs.theropay.co/theropay/docs/reference/payouts/payee/paths/~1v1~1payees~1list/post.md): Lists all payees with optional pagination and sorting.

## Fees

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

### Get Fees

 - [POST /api/v1/fees/calculate](https://docs.theropay.co/theropay/docs/reference/payouts/fees/paths/~1api~1v1~1fees~1calculate/post.md)

## Payout Endpoints

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

### Initiates a payout to a payee.

 - [POST /v1/payouts](https://docs.theropay.co/theropay/docs/reference/payouts/payout-endpoints/paths/~1v1~1payouts/post.md): 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.

### Retrieves a list of payouts for a specific payee.

 - [GET /v1/payouts](https://docs.theropay.co/theropay/docs/reference/payouts/payout-endpoints/paths/~1v1~1payouts/get.md)