Skip to content
Payouts
/Webhook/
/
Handling Webhooks

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.

payout.cancelled

{
  "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/1.1 200 OK
Content-Type: application/json

{
  "status": "received"
}

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

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