Skip to content
/Payee

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

Creates a new payee.

Request

Use this endpoint to create a new payee.

  • Tax ID are optional for individual payee type.
  • Tax ID are required for business payee type.
Security
Bearer
Body

Payee creation request payload.

payeeTypestringnon-empty(individual|business)required

Payee type: "individual" or "business".

namestring[ 0 .. 100 ] charactersrequired

Full legal name of the payee.

EmailAddressstringnon-emptyrequired

EmailAddress of the payee.

phoneNumberstring or null

Phone number (optional for individual, required for business payees).

taxIdstring or null[ 0 .. 50 ] characters

Tax identifier (optional for individual, required for business payees).

idTypestring or null[ 0 .. 50 ] characters

Type of government-issued ID.

addressobject(AddressRequest)required
address.​addressLinestring[ 0 .. 200 ] charactersrequired
address.​statestring[ 0 .. 100 ] charactersrequired
address.​citystring[ 0 .. 100 ] charactersrequired
address.​countrystring[ 0 .. 100 ] charactersrequired
address.​postalCodestring[ 0 .. 20 ] charactersrequired
dateOfBirthstring(optional)(format-date)
curl -i -X POST \
  https://docs.theropay.co/_mock/theropay/docs/reference/api/v1/payees \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "payeeType": "string",
    "name": "string",
    "EmailAddress": "string",
    "phoneNumber": "string",
    "taxId": "string",
    "idType": "string",
    "address": {
      "addressLine": "string",
      "state": "string",
      "city": "string",
      "country": "string",
      "postalCode": "string"
    },
    "dateOfBirth": null
  }'

Responses

Payee created successfully.

Body
payeeTypeindividual or business
namestring or null
EmailAddressstring or null
phoneNumberstring or null
taxIdstring or null
idTypestring or null
addressobject(AddressResponseDto)
dateOfBirthstring(date)
Response
No response example

Retrieves a payee by ID.

Request

Security
Bearer
Path
idintegerrequired

Unique identifier of the payee.

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

Responses

Payee retrieved successfully.

Body
payeeTypeindividual or business
namestring or null
EmailAddressstring or null
phoneNumberstring or null
taxIdstring or null
idTypestring or null
addressobject(AddressResponseDto)
dateOfBirthstring(date)
Response
No response example

Updates an existing payee.

Request

Security
Bearer
Path
idstring

Unique identifier of the payee to update.

Body

Updated payee details.

payeeTypestring
Enum"individual""business"
namestring
EmailAddressstring
phoneNumberstring
taxIdstring (Optional in case of individual and required in case of business type)(uuid)
idTypestring
addressobject(AddressRequest)required
address.​addressLinestring[ 0 .. 200 ] charactersrequired
address.​statestring[ 0 .. 100 ] charactersrequired
address.​citystring[ 0 .. 100 ] charactersrequired
address.​countrystring[ 0 .. 100 ] charactersrequired
address.​postalCodestring[ 0 .. 20 ] charactersrequired
dateOfBirthstring(date)
curl -i -X PATCH \
  'https://docs.theropay.co/_mock/theropay/docs/reference/api/v1/payees/{id}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "payeeType": "individual",
    "name": "string",
    "EmailAddress": "string",
    "phoneNumber": "string",
    "taxId": null,
    "idType": "string",
    "address": {
      "addressLine": "string",
      "state": "string",
      "city": "string",
      "country": "string",
      "postalCode": "string"
    },
    "dateOfBirth": "2019-08-24"
  }'

Responses

Payee updated successfully.

Body
payeeTypeindividual or business
namestring or null
EmailAddressstring or null
phoneNumberstring or null
taxIdstring or null
idTypestring or null
addressobject(AddressResponseDto)
dateOfBirthstring(date)
Response
No response example

Lists all payees.

Request

Security
Bearer
Body
payeeTypestring
Enum"individual""business"
namestring
EmailAddressstring
phoneNumberstring
taxIdstring (Optional in case of individual and required in case of business type)(uuid)
idTypestring
addressobject(AddressRequest)required
address.​addressLinestring[ 0 .. 200 ] charactersrequired
address.​statestring[ 0 .. 100 ] charactersrequired
address.​citystring[ 0 .. 100 ] charactersrequired
address.​countrystring[ 0 .. 100 ] charactersrequired
address.​postalCodestring[ 0 .. 20 ] charactersrequired
dateOfBirthstring(date)
curl -i -X POST \
  https://docs.theropay.co/_mock/theropay/docs/reference/api/v1/payees/list \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "payeeType": "individual",
    "name": "string",
    "EmailAddress": "string",
    "phoneNumber": "string",
    "taxId": null,
    "idType": "string",
    "address": {
      "addressLine": "string",
      "state": "string",
      "city": "string",
      "country": "string",
      "postalCode": "string"
    },
    "dateOfBirth": "2019-08-24"
  }'

Responses

List of payees retrieved successfully.

Body
Array [
payeeTypeindividual or business
namestring or null
EmailAddressstring or null
phoneNumberstring or null
taxIdstring or null
idTypestring or null
addressobject(AddressResponseDto)
dateOfBirthstring(date)
]
Response
No response example

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