# Theropay APIs

Theropay offers a set of powerful APIs that help merchants manage their payment processes. These APIs allow you to handle everything from managing payees and setting up payout accounts to tracking and initiating payments.


## Servers

Production server
```
https://api.theropay.com
```

## Security

### Bearer

JWT Authorization header using the Bearer scheme.

Type: http
Scheme: bearer
Bearer Format: JWT

## Download OpenAPI description

[Theropay APIs](https://docs.theropay.cloud/_bundle/Theropay/docs/reference/api.yaml)

## Payee

The Payees API allows you to manage your payees easily. 
You can create new payees, update their information, list all 
payees, or deactivate them when needed. Each payee can be an 
individual or a business. This API helps keep track of all your 
payees in one place.
Think of it as your digital address book for payments. 
It ensures that every transaction is sent to the correct and verified recipient, 
simplifying the payout process for your application. 

### Creates a new payee.

 - [POST /v1/payees](https://docs.theropay.cloud/theropay/docs/reference/api/payee/paths/~1v1~1payees/post.md): Use this endpoint to create a new payee.  
- Tax ID are optional for individual payee type.  
- Tax ID are required for business payee type.

### Retrieves a payee by ID.

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

### Updates an existing payee.

 - [PATCH /v1/payees/{id}](https://docs.theropay.cloud/theropay/docs/reference/api/payee/paths/~1v1~1payees~1%7Bid%7D/patch.md)

### Lists all payees.

 - [POST /v1/payees/list](https://docs.theropay.cloud/theropay/docs/reference/api/payee/paths/~1v1~1payees~1list/post.md)

## Payee Accounts

The Payee Accounts API allows merchants to manage the bank or payout accounts linked to their payees.
It enables creating, updating, and retrieving payout account details securely. 
Each payee can have one or more accounts associated for receiving funds.
Use these endpoints to validate account information and ensure smooth disbursements.
This API acts as the secure layer between your system and the banks, handling sensitive financial data.

### Add a payout account to payee

 - [POST /v1/payees/{id}/accounts](https://docs.theropay.cloud/theropay/docs/reference/api/payee-accounts/paths/~1v1~1payees~1%7Bid%7D~1accounts/post.md): Add a payout account to the specified payee (matches user story).

### List all payout accounts for a payee

 - [GET /v1/payees/{id}/accounts](https://docs.theropay.cloud/theropay/docs/reference/api/payee-accounts/paths/~1v1~1payees~1%7Bid%7D~1accounts/get.md): Returns a list of all payout accounts associated with the specified payee. Matches user story.

### Retrieve specific payout account

 - [GET /v1/payees/{id}/accounts/{account_id}](https://docs.theropay.cloud/theropay/docs/reference/api/payee-accounts/paths/~1v1~1payees~1%7Bid%7D~1accounts~1%7Baccount_id%7D/get.md): Returns complete details of a specific payout account for the given payee.

### Update payout account

 - [PATCH /v1/payees/{id}/accounts/{account_id}](https://docs.theropay.cloud/theropay/docs/reference/api/payee-accounts/paths/~1v1~1payees~1%7Bid%7D~1accounts~1%7Baccount_id%7D/patch.md): Use this endpoint to modify payout account details (matches user story).

### Disable payout account

 - [DELETE /v1/payees/{id}/accounts/{account_id}](https://docs.theropay.cloud/theropay/docs/reference/api/payee-accounts/paths/~1v1~1payees~1%7Bid%7D~1accounts~1%7Baccount_id%7D/delete.md): Disables a payout account (sets active flag to false) as per user story.

## Payouts

The Payouts API allows merchants to send money to their payees securely and efficiently. 
You can create new payouts, check their status, and cancel them if needed before processing. 
Each payout is linked to a registered payee and a payout account. 
The API supports listing all payouts with optional filters like status. 
Responses include detailed information about the payout, such as amount, currency, and current status. 
Use this API to manage your outgoing payments in a reliable and predictable way.

### Initiates a payout to a payee.

 - [POST /v1/payouts](https://docs.theropay.cloud/theropay/docs/reference/api/payouts/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.cloud/theropay/docs/reference/api/payouts/paths/~1v1~1payouts/get.md)

### Retrieves details of a specific payout by unique reference.

 - [GET /v1/payouts/{PayoutUniqueReference}](https://docs.theropay.cloud/theropay/docs/reference/api/payouts/paths/~1v1~1payouts~1%7Bpayoutuniquereference%7D/get.md)

### Requests cancellation of a pending payout.

 - [POST /v1/payouts/{PayoutUniqueReference}/cancel](https://docs.theropay.cloud/theropay/docs/reference/api/payouts/paths/~1v1~1payouts~1%7Bpayoutuniquereference%7D~1cancel/post.md): Only payouts not yet processed can be cancelled.  
Completed or failed payouts cannot be cancelled.

## Webhook

# About Webhooks

> Webhooks are automatic messages sent from our system to your server whenever something important happens with a payout.  
> Think of them like **notifications** — they instantly let you know when the status of a payout changes.
> 
> Your server must be able to accept **HTTPS POST requests** and respond with standard HTTP status codes.  
> Each webhook payload is delivered in **JSON** format.

---
## When Are Webhooks Sent?

We send a webhook every time a payout moves to a new stage in its lifecycle.  
Here are the possible events:

- `payout.created` – A new payout has been created and recorded in the system.  
- `payout.processing` – The payout is currently being processed.    
- `payout.sent` – The payout has been sent to the bank or payment provider.  
- `payout.completed` – The payout was successfully delivered.  
- `payout.failed` – The payout could not be completed due to an error.  
- `payout.cancelled` – The payout was cancelled before completion.

These webhook notifications help you **track every stage** of a payout in real time.

---

## Webhook Payload Schemas

Below are example payloads for each webhook event.  
All payloads share a similar structure, with the main difference being the `state` value and any additional fields such as `reasons`.

---

###  `payout.created`

```json
{
  "payout_request_id": "PR123456789",
  "amount": "100.00",
  "currency": "EUR",
  "timestamp": "2025-01-09T10:24:15Z",
  "state": "created"
}
```

---

###  `payout.processing`

```json
{
  "payout_request_id": "PR123456789",
  "amount": "100.00",
  "currency": "EUR",
  "timestamp": "2025-01-09T10:25:30Z",
  "state": "processing"
}
```
---

###  `payout.sent`

```json
{
  "payout_request_id": "PR123456789",
  "amount": "100.00",
  "currency": "EUR",
  "timestamp": "2025-01-09T10:35:00Z",
  "state": "sent"
}
```

---

###  `payout.completed`

```json
{
  "payout_request_id": "PR123456789",
  "amount": "100.00",
  "currency": "EUR",
  "timestamp": "2025-01-09T10:40:00Z",
  "state": "completed"
}
```
---

###  `payout.failed`

```json
{
  "payout_request_id": "PR123456789",
  "amount": "100.00",
  "currency": "EUR",
  "timestamp": "2025-01-09T10:45:00Z",
  "state": "failed"
}
```

---

###  `payout.cancelled`

```json
{
  "payout_request_id": "PR123456789",
  "amount": "100.00",
  "currency": "EUR",
  "timestamp": "2025-01-09T10:50:00Z",
  "state": "cancelled"
}
```

---

## Handling Webhooks

When Theropay sends your system a **webhook**, it’s sending a message to let you know that something happened — for example, a payout was completed.

Here’s what you need to do step by step:

1. **Read the webhook message (payload)**  
   - The webhook contains data in **JSON format**.  
   - This data includes details such as the payout ID, amount, and current status.  
   - Theropay **does not include a signature** with the webhook, so you don’t need to verify one.

2. **Update your system**  
   - Use the information from the webhook to update your records.  
   - For example, if the webhook says a payout is complete, mark that payout as “completed” in your system.  
   - Make sure to handle the webhook data carefully — since Theropay only sends it **once**, your system should be ready to process it correctly the first time.

3. **Send a response back to Theropay**  
   - After you’ve successfully received and processed the webhook, send back an **`HTTP 200 OK`** response.  
   - This confirms to Theropay that your system got the message.  
   - Since Theropay **only sends the webhook once**, if your system fails to respond or process it correctly, you won’t receive it again.

---

### Example Response

```http
HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "received"
}
```

---

> 💡 **Tip:**  
> Always log incoming webhook events for debugging and verification purposes.

### Creating a Webhook

You can create a webhook to receive payout events for your system. 
This involves registering your server endpoint with our API.
Instead of your system constantly checking for updates, we “push” the information to you in real time.

1. Copy your server URL where you want to receive webhooks.
2. Go to the **Webhooks API endpoint** in this documentation.
3. Click **Try it out**.
4. Paste your URL, select the events you want, and choose **sandbox** or **production**.
5. Click **Execute** to register the webhook.
6. Check your server or test endpoint to see the webhook payloads in real time.

**Note :  Test in Sandbox First**
> Always start by creating the webhook in the sandbox environment.
> This allows you to test your endpoint without affecting real payouts.
> Once everything works, you can register the webhook in production for live notifications.







### Registers a new webhook to receive Payout.

 - [POST /v1/webhooks](https://docs.theropay.cloud/theropay/docs/reference/api/webhook/paths/~1v1~1webhooks/post.md)

### Retrieves all registered webhooks for the merchant.

 - [GET /v1/webhooks](https://docs.theropay.cloud/theropay/docs/reference/api/webhook/paths/~1v1~1webhooks/get.md)

### Deletes a registered webhook by its unique ID.

 - [DELETE /v1/webhooks](https://docs.theropay.cloud/theropay/docs/reference/api/webhook/paths/~1v1~1webhooks/delete.md)