Skip to content
/Payee Accounts

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

Add a payout account to payee

Request

Add a payout account to the specified payee (matches user story).

Security
Bearer
Path
idintegerrequired

Unique identifier of the payee to whom the account will be linked.

Body
required

Payout account details as per user story.

typestring or nullrequired
Enum"BANK_ACCOUNT""IBAN"
accountHolderNamestring or nullrequired

Required if type is BANK_ACCOUNT

bankNamestring or null

Required if type is BANK_ACCOUNT

routingNumberstring or null

Required if type is BANK_ACCOUNT

accountNumberstring or null

Required if type is BANK_ACCOUNT

bankClearingSystemCodestring
branchTransitNumberstring or null
IBANstring or null

Required if type is IBAN

Currencystring or null
accountTypestring

Required if type is BANK_ACCOUNT

Enum"CHECKINGS""SAVINGS"
curl -i -X POST \
  'https://docs.theropay.co/_mock/theropay/docs/reference/api/v1/payees/{id}/accounts' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "BANK_ACCOUNT",
    "accountHolderName": "string",
    "bankName": "string",
    "routingNumber": "string",
    "accountNumber": "string",
    "bankClearingSystemCode": "string",
    "branchTransitNumber": "string",
    "IBAN": "string",
    "Currency": "string",
    "accountType": "CHECKINGS"
  }'

Responses

PayeeAccountId

Bodyapplication/json
PayeeAccountIdstring
Example: "1234567890"
Response
application/json
{
  "PayeeAccountId": "1234567890"
}

List all payout accounts for a payee

Request

Returns a list of all payout accounts associated with the specified payee. Matches user story.

Security
Bearer
Path
payeeAccountIdinteger

Unique identifier of the payee whose accounts are to be retrieved.

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

Responses

Payout accounts retrieved successfully.

Bodyapplication/jsonArray [
payeeIdstring or null
payeeAccountIdstring or null
typestring or null
Enum"BANK_ACCOUNT""IBAN"
accountHolderNamestring or null
bankNamestring or null
routingNumberstring or null
accountNumberstring or null

Token - Last 4 Digits (responses return last 4 digits only)

branchTransitNumberstring or null
IBANstring or null
Currencystring or null
accountTypestring
Enum"CHECKINGS""SAVINGS"
accountTypeIdinteger
createdOnstring(date)
]
Response
application/json
[
  {
    "payeeId": "string",
    "payeeAccountId": "string",
    "type": "BANK_ACCOUNT",
    "accountHolderName": "string",
    "bankName": "string",
    "routingNumber": "string",
    "accountNumber": "string",
    "branchTransitNumber": "string",
    "IBAN": "string",
    "Currency": "string",
    "accountType": "CHECKINGS",
    "accountTypeId": 0,
    "createdOn": "2019-08-24"
  }
]

Retrieve specific payout account

Request

Returns complete details of a specific payout account for the given payee.

Security
Bearer
Path
payeeAccountIdintegerrequired

Unique identifier of the payee who owns the payout account.

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

Responses

Payout account details retrieved successfully.

Bodyapplication/json
payeeIdstring or null
payeeAccountIdstring or null
typestring or null
Enum"BANK_ACCOUNT""IBAN"
accountHolderNamestring or null
bankNamestring or null
routingNumberstring or null
accountNumberstring or null

Token - Last 4 Digits (responses return last 4 digits only)

branchTransitNumberstring or null
IBANstring or null
Currencystring or null
accountTypestring
Enum"CHECKINGS""SAVINGS"
accountTypeIdinteger
createdOnstring(date)
Response
application/json
{
  "payeeId": "string",
  "payeeAccountId": "string",
  "type": "BANK_ACCOUNT",
  "accountHolderName": "string",
  "bankName": "string",
  "routingNumber": "string",
  "accountNumber": "string",
  "branchTransitNumber": "string",
  "IBAN": "string",
  "Currency": "string",
  "accountType": "CHECKINGS",
  "accountTypeId": 0,
  "createdOn": "2019-08-24"
}

Update payout account

Request

Use this endpoint to modify payout account details (matches user story).

Security
Bearer
Path
idintegerrequired

Unique identifier of the payee who owns the payout account.

account_idstringrequired

Unique identifier of the payout account to update.

Body

Payload containing updated payout account information.

typestring or nullrequired
Enum"BANK_ACCOUNT""IBAN"
accountHolderNamestring or nullrequired

Required if type is BANK_ACCOUNT

bankNamestring or null

Required if type is BANK_ACCOUNT

routingNumberstring or null

Required if type is BANK_ACCOUNT

accountNumberstring or null

Required if type is BANK_ACCOUNT

bankClearingSystemCodestring
branchTransitNumberstring or null
IBANstring or null

Required if type is IBAN

Currencystring or null
accountTypestring

Required if type is BANK_ACCOUNT

Enum"CHECKINGS""SAVINGS"
curl -i -X PATCH \
  'https://docs.theropay.co/_mock/theropay/docs/reference/api/v1/payees/{id}/accounts/{account_id}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "BANK_ACCOUNT",
    "accountHolderName": "string",
    "bankName": "string",
    "routingNumber": "string",
    "accountNumber": "string",
    "bankClearingSystemCode": "string",
    "branchTransitNumber": "string",
    "IBAN": "string",
    "Currency": "string",
    "accountType": "CHECKINGS"
  }'

Responses

Payout account updated successfully.

Bodyapplication/json
payeeIdstring or null
payeeAccountIdstring or null
typestring or null
Enum"BANK_ACCOUNT""IBAN"
accountHolderNamestring or null
bankNamestring or null
routingNumberstring or null
accountNumberstring or null

Token - Last 4 Digits (responses return last 4 digits only)

branchTransitNumberstring or null
IBANstring or null
Currencystring or null
accountTypestring
Enum"CHECKINGS""SAVINGS"
accountTypeIdinteger
createdOnstring(date)
Response
application/json
{
  "payeeId": "string",
  "payeeAccountId": "string",
  "type": "BANK_ACCOUNT",
  "accountHolderName": "string",
  "bankName": "string",
  "routingNumber": "string",
  "accountNumber": "string",
  "branchTransitNumber": "string",
  "IBAN": "string",
  "Currency": "string",
  "accountType": "CHECKINGS",
  "accountTypeId": 0,
  "createdOn": "2019-08-24"
}

Disable payout account

Request

Disables a payout account (sets active flag to false) as per user story.

Security
Bearer
Path
idintegerrequired

Unique identifier of the payee who owns the payout account.

account_idstringrequired

Unique identifier of the payout account to disable.

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

Responses

Payout account disabled successfully

Bodyapplication/json
accountIdstring or null
messagestring or null
Response
application/json
{
  "accountId": "string",
  "message": "string"
}

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