# Welcome to Theropay

Theropay helps you send money across the world — safely, quickly, and with just a few clicks.
Our API makes it easy for businesses to pay their partners, freelancers, or employees, no matter where they live.

If you’ve ever needed to send international payments or manage multiple payees, Theropay is built exactly for that.
This guide will help you understand how everything works and show you how to get started.

## What You Can Achieve with Theropay

Theropay’s API is designed to help you manage the full payment journey — from creating a payee to sending their payout and checking its status.

### 1. Manage Your Payees

Your payees are the people or businesses you send money to.
With our API, you can:

- **Add new payees** — individuals or companies.
- **View and update payee information** — keep their details up to date.
- **Check their KYC (Know Your Customer) status** to make sure everything is verified.
- **Add payout accounts** — the bank accounts where they’ll receive their funds.
- **Deactivate payees** — safely disable payees who no longer need to receive payouts.


**Example endpoints:**

| Action | Endpoint |
|  --- | --- |
| Create a payee | `POST /v1/payees` |
| Retrieve a payee | `GET /v1/payees/{id}` |
| List payees | `GET /v1/payees` |
| Update a payee | `PATCH /v1/payees/{id}` |
| Disable a payee | `DELETE /v1/payees/{id}` |
| Generate KYC verification link | `POST /v1/payees/{id}/kyc-link` |
| Get KYC status | `GET /v1/payees/{id}/kyc-status` |
| Add payout account | `POST /v1/payees/{id}/accounts` |
| List payout accounts | `GET /v1/payees/{id}/accounts` |
| Retrieve specific payout account | `GET /v1/payees/{id}/accounts/{account_id}` |
| Update payout account | `PATCH /v1/payees/{id}/accounts/{account_id}` |
| Disable payout account | `DELETE /v1/payees/{id}/accounts/{account_id}` |


### 2. Send and Track Payouts

Once your payees are verified, you can start sending them money.
You can:

- **Create a payout** with just one API call.
- **Cancel a payout** if it hasn’t been processed yet.
- **Track every payout** to see if it’s pending, sent, or completed.


**Example endpoints:**

| Action | Endpoint |
|  --- | --- |
| Create a payout | `POST /v1/payouts` |
| Retrieve a payout | `GET /v1/payouts/{id}` |
| List payouts | `GET /v1/payouts` |
| Cancel a payout | `POST /v1/payouts/{id}/cancel` |


### 3. Keep Your Finances in Sync

Stay up to date with your funds and currency information:

- **Check balances** in different currencies.
- **Get exchange rates** for conversions.
- **View available payout methods** for each country.


This helps you plan payouts and track your business finances in real time.

**Example endpoints:**

| Action | Endpoint |
|  --- | --- |
| Get available balances | `GET /v1/balances` |
| List payout methods (by country) | `GET /v1/payout-methods?country=CA` |


## How the API Works

Theropay’s API follows simple, consistent rules so developers can build with confidence.

- **Versioning:** All endpoints start with `/v1/` so your integration stays stable.
- **Idempotency:** Avoid sending the same payout twice — use an `Idempotency-Key` to keep things safe.
- **Pagination:** Get results in easy-to-handle chunks when listing large sets of data.
- **Authentication:** Every request needs a valid API token for security.


## Clear Error Messages

If something goes wrong, you’ll get a clear and consistent JSON error message.
Each response tells you:

- What happened (`message`)
- The type of error (`code`)
- The HTTP status (`status`)


This makes debugging quick and stress-free.

## Real-Time Notifications (Webhooks)

Theropay can automatically notify your system when something changes — like when a payout completes or a payee passes verification.
You don’t need to keep checking the API yourself.

You can receive webhook alerts for:

- **Payout updates** — created, processing, completed, or failed.


## Get Started

The best place to begin is the **Authentication** section.
There, you’ll learn how to create your first access token and make your first API call.

Once you’re set up, you can explore our **Payees**, **Payouts**, and **Balances** endpoints.

Welcome aboard — let’s make global payouts simple together!