Skip to content
Payouts
/
/
Registers a new webhook t...

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.

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

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

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