Skip to content
Payouts
/Webhook/
/
Creating a Webhook

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.

Download OpenAPI description
api.json
api.yaml
Languages
Servers
Mock server

https://docs.theropay.co/_mock/theropay/docs/reference/api/

Production server

https://api.theropay.com/

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.

Operations

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.

Operations

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.

Operations

Webhook

Operations

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.

Example Response

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.

Request

Security
Bearer
Body

Webhook registration details including URL, environment, and events.

urlstring or nullrequired
curl -i -X POST \
  https://docs.theropay.co/_mock/theropay/docs/reference/api/v1/webhooks \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "string"
  }'

Responses

Webhook created successfully.

Body
idstring(uuid)
urlstring or null
Response
No response example

Retrieves all registered webhooks for the merchant.

Request

Security
Bearer
curl -i -X GET \
  https://docs.theropay.co/_mock/theropay/docs/reference/api/v1/webhooks \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Webhooks retrieved successfully.

Body
Array [
idstring(uuid)
urlstring or null
]
Response
No response example

Deletes a registered webhook by its unique ID.

Request

Security
Bearer
Path
idstring(uuid)required

The unique identifier of the webhook to delete.

curl -i -X DELETE \
  https://docs.theropay.co/_mock/theropay/docs/reference/api/v1/webhooks \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Webhook deleted successfully.

Response
No content