Skip to content
/Endpoints

Overview

The Partners API enables authorized integration partners to collaborate with associated merchants.

Payment requests, payees, and payment status can all be created by partners.

OAuth2 Client Credentials are used to grant secure access.

For More Information Please read the full Partner Integration Guide here:

Partner Integration Guide

Download OpenAPI description
Partners.json
Partners.yaml
Overview
API Support
support@theropay.io
Languages
Servers
Mock server
https://docs.theropay.co/_mock/theropay/docs/reference/partners
Sandbox Server
https://devapi.theropay.co

Endpoints

These are the main endpoints used by partners. They allow you to create payment requests and check payment status. Partners can only access data for merchants linked to them. All requests must include a valid access token

Operations

Generate a Token

Request

This API generates an access token using the clientId and clientSecret provided to the partner during onboarding.

Security
Bearer
Body
required
clientIdstringrequired

(Required) Unique identifier assigned to the client application

clientSecretstringrequired

(Required) Secret key associated with the clientId for authentication.

curl -i -X POST \
  https://docs.theropay.co/_mock/theropay/docs/reference/partners/finance/v1/generate-token \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "clientId": "string",
    "clientSecret": "string"
  }'

Responses

OK

Bodyapplication/json
clientIdstring
clientSecretstring
Response
application/json
{
  "clientId": "string",
  "clientSecret": "string"
}

Retrieves a list of merchants linked to the partner.

Request

This API returns all merchants assigned to the given partner. Pass the partnerId as a query parameter.

Security
Bearer
Query
partnerIdintegerrequired

The unique ID of the partner whose merchants you want to fetch.

curl -i -X GET \
  'https://docs.theropay.co/_mock/theropay/docs/reference/partners/finance/v1/partner/list?partnerId=0' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successfully returned the list of merchants.

Bodyapplication/json
messageArray of strings
dataArray of objects(PartnerMerchantEntry)
Response
application/json
{
  "message": [
    "string"
  ],
  "data": [
    { … }
  ]
}

Creates a new recipient using ACH.

Request

Create a counterparty (payee) for a merchant. Include partner and merchant IDs.

Security
Bearer
Body
required

Request object containing payee and payment method details.

emailstring(email)required

(Required) Email address of the counterparty.

namestringrequired

(Required) Full name of the counterparty.

phonestring

(Optional) Contact phone in E.164 format.

typestring

(Optional) Counterparty type.

Default "INDIVIDUAL"
Enum"INDIVIDUAL""BUSINESS"
paymentMethodTypestring

(Required) Payment method type for this payee (e.g., ACH).

partnerIdintegerrequired

(Required) Partner ID assigned to your integration.

merchantIdintegerrequired

(Required) Merchant ID under which this payee will be created.

achobject(AchPayment)required
ach.​accountNumberstringrequired

(Required) Bank account number.

ach.​bankAccountTypestringrequired

(Required) Account type.

Enum"CHECKING""SAVINGS"
ach.​bankNamestring

(Optional) Bank name.

ach.​routingNumberstringrequired

(Required) Routing number (9 digits).

ach.​addressobject(Address)required
ach.​address.​citystringrequired

(Required) City name.

ach.​address.​countryCodestringrequired

(Required) ISO country code (2 letters).

ach.​address.​line1stringrequired

(Required) Primary street line.

ach.​address.​line2string

(Optional) Secondary street line.

ach.​address.​postalCodestringrequired

(Required) Postal or ZIP code.

ach.​address.​statestringrequired

(Required) State or province code.

ach.​address.​typestring

(Optional) Address type.

Enum"RESIDENCE""MAILING""BUSINESS"
curl -i -X POST \
  https://docs.theropay.co/_mock/theropay/docs/reference/partners/finance/v1/recipient-ach \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "user@example.com",
    "name": "string",
    "phone": "string",
    "type": "INDIVIDUAL",
    "paymentMethodType": "string",
    "partnerId": 0,
    "merchantId": 0,
    "ach": {
      "accountNumber": "string",
      "bankAccountType": "CHECKING",
      "bankName": "string",
      "routingNumber": "string",
      "address": {
        "city": "string",
        "countryCode": "string",
        "line1": "string",
        "line2": "string",
        "postalCode": "string",
        "state": "string",
        "type": "RESIDENCE"
      }
    }
  }'

Responses

OK

Bodyapplication/json
emailstring
namestring
phonestring
typestring
paymentMethodTypestring
partnerIdinteger
merchantIdinteger
achobject(AchDetails)
Response
application/json
{
  "email": "string",
  "name": "string",
  "phone": "string",
  "type": "string",
  "paymentMethodType": "string",
  "partnerId": 0,
  "merchantId": 0,
  "ach": {
    "accountNumber": "string",
    "bankAccountType": "string",
    "bankName": "string",
    "routingNumber": "string",
    "address": { … }
  }
}

Creates a new recipient using Wire transfer.

Request

Create a counterparty (payee) for wire payments. Supports both domestic and international wire transfers. Provide partnerId, merchantId, and wire details.

Security
Bearer
Body
required
emailstring(email)required

(Required) Email address of the counterparty.

namestringrequired

(Required) Full legal name of the counterparty.

phonestring

(Optional) Contact phone number.

typestring

(Optional) Counterparty type.

Default "INDIVIDUAL"
Enum"INDIVIDUAL""BUSINESS"
paymentMethodTypestringrequired

(Required) Payment method type.

Enum"DOMESTIC_WIRE""INTERNATIONAL_WIRE"
partnerIdintegerrequired

(Required) Assigned partner ID.

merchantIdintegerrequired

(Required) Merchant ID under which the payee is created.

wireobject(WirePayment)required
wire.​receiverRoutingNumberstringrequired

(Required) Receiver routing number.

wire.​beneficiaryAccountNumberstringrequired

(Required) Beneficiary’s bank account number.

wire.​beneficiaryFINamestringrequired

(Required) Beneficiary financial institution name.

wire.​typestringrequired

(Required) Type of wire transfer.

Enum"DOMESTIC""INTERNATIONAL"
wire.​receiverShortNamestring or null

(Optional) Short name for receiver.

wire.​beneficiaryFIIdTypestringrequired

(Required) Beneficiary financial institution ID type.

Enum"ABA""BIC"
wire.​beneficiaryIdNumberstring or null

(Optional) Beneficiary ID number (TIN/EIN/etc.).

wire.​intermediaryFINamestring or null

(Optional) Intermediary financial institution name.

wire.​intermediaryFIIdNumberstring or null

(Optional) Intermediary FI ID number.

wire.​intermediaryFIIdTypestring or null

(Optional) Intermediary FI ID type.

Enum"ABA""BIC"
wire.​intermediaryFIAddressobject(WireAddress)
wire.​addressobject(WireAddress)required
wire.​address.​citystringrequired

City name.

wire.​address.​countryCodestringrequired

ISO country code.

wire.​address.​line1stringrequired

Primary street line.

wire.​address.​line2string or null

(Optional) Secondary street line.

wire.​address.​postalCodestringrequired

Postal or ZIP code.

wire.​address.​statestringrequired

State or province code.

wire.​address.​typestring

(Optional) Address type.

Enum"RESIDENCE""MAILING""BUSINESS"
wire.​beneficiaryFIAddressobject(WireAddress)
curl -i -X POST \
  https://docs.theropay.co/_mock/theropay/docs/reference/partners/finance/v1/recipient-wire \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "user@example.com",
    "name": "string",
    "phone": "string",
    "type": "INDIVIDUAL",
    "paymentMethodType": "DOMESTIC_WIRE",
    "partnerId": 0,
    "merchantId": 0,
    "wire": {
      "receiverRoutingNumber": "string",
      "beneficiaryAccountNumber": "string",
      "beneficiaryFIName": "string",
      "type": "DOMESTIC",
      "receiverShortName": "string",
      "beneficiaryFIIdType": "ABA",
      "beneficiaryIdNumber": "string",
      "intermediaryFIName": "string",
      "intermediaryFIIdNumber": "string",
      "intermediaryFIIdType": "ABA",
      "intermediaryFIAddress": {
        "city": "string",
        "countryCode": "string",
        "line1": "string",
        "line2": "string",
        "postalCode": "string",
        "state": "string",
        "type": "RESIDENCE"
      },
      "address": {
        "city": "string",
        "countryCode": "string",
        "line1": "string",
        "line2": "string",
        "postalCode": "string",
        "state": "string",
        "type": "RESIDENCE"
      },
      "beneficiaryFIAddress": {
        "city": "string",
        "countryCode": "string",
        "line1": "string",
        "line2": "string",
        "postalCode": "string",
        "state": "string",
        "type": "RESIDENCE"
      }
    }
  }'

Responses

Payee created successfully.

Bodyapplication/json
emailstring
namestring
phonestring
typestring
paymentMethodTypestring
partnerIdinteger
merchantIdinteger
wireobject(WireDetails)
Response
application/json
{
  "email": "string",
  "name": "string",
  "phone": "string",
  "type": "string",
  "paymentMethodType": "string",
  "partnerId": 0,
  "merchantId": 0,
  "wire": {
    "receiverRoutingNumber": "string",
    "beneficiaryAccountNumber": "string",
    "beneficiaryFIName": "string",
    "type": "string",
    "receiverShortName": "string",
    "beneficiaryFIIdType": "string",
    "beneficiaryIdNumber": "string",
    "intermediaryFIName": "string",
    "intermediaryFIIdNumber": "string",
    "intermediaryFIIdType": "string",
    "intermediaryFIAddress": { … },
    "address": { … },
    "beneficiaryFIAddress": { … }
  }
}

Get Recipients

Request

Security
Bearer
Query
MerchantIdinteger(int32)
PartnerIdinteger(int32)
PayeeTypestring
PaymentNetworkRailPayeeIdinteger(int32)
SearchTextstring
PayeePaymentMethodTypestring
PageNumberinteger(int32)
PageSizeinteger(int32)
Routestring
SortPropertystring
IsDescendingboolean
curl -i -X GET \
  'https://docs.theropay.co/_mock/theropay/docs/reference/partners/finance/v1/payees?MerchantId=0&PartnerId=0&PayeeType=string&PaymentNetworkRailPayeeId=0&SearchText=string&PayeePaymentMethodType=string&PageNumber=0&PageSize=0&Route=string&SortProperty=string&IsDescending=true' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

OK

Bodyapplication/json
MerchantIdinteger(int32)
PartnerIdinteger(int32)
PayeeTypestring
SearchTextstring
PayeePaymentMethodTypestring
PageNumberinteger(int32)
PageSizeinteger(int32)
Routestring
SortPropertystring
IsDescendingboolean
Response
application/json
{
  "MerchantId": 0,
  "PartnerId": 0,
  "PayeeType": "string",
  "SearchText": "string",
  "PayeePaymentMethodType": "string",
  "PageNumber": 0,
  "PageSize": 0,
  "Route": "string",
  "SortProperty": "string",
  "IsDescending": true
}

Create a new payment Request.

Request

Create a payment on behalf of a merchant. Provide partner and merchant IDs and a unique partner payment ID for idempotency.

Security
Bearer
Body
required
payeeIdinteger(int32)required

(Required) ID of the payee created earlier.

merchantAccountNumberstring or null<= 100 characters
amountinteger(int64)>= 0.01required

(Required) Amount to send. Must be greater than 0.

currencystring or null

(Optional) Currency code in ISO 4217 format. Default:USD

paymentMethodTypestringnon-emptyrequired

(Required) Payment method type

Enum"STANDARD""SAME_DAY""DOMESTIC_WIRE""INTERNATIONAL_WIR"
descriptionstring[ 1 .. 500 ] charactersrequired

(Required) Description of the payment (max 500 chars).

externalIdstring or null

(Optional) External identifier if needed.

internalNotestring or null

(Optional) Internal note for the payment.

partnerIdinteger or null(int32)required

(Required) Partner ID assigned to your integration.

merchantIdinteger or null(int32)required

(Required) Merchant ID under which this payment is initiated.

partnerPaymentUniqueIdstring or null

(Required) Unique partner payment identifier for idempotency.

curl -i -X POST \
  https://docs.theropay.co/_mock/theropay/docs/reference/partners/finance/v1/payment_request \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "payeeId": 0,
    "merchantAccountNumber": "string",
    "amount": 0.01,
    "currency": "string",
    "paymentMethodType": "STANDARD",
    "description": "string",
    "externalId": "string",
    "internalNote": "string",
    "partnerId": 0,
    "merchantId": 0,
    "partnerPaymentUniqueId": "string"
  }'

Responses

OK

Bodyapplication/json
payeeIdinteger
amountnumber(decimal)
currencystring
paymentMethodTypestring
descriptionstring
partnerIdinteger
merchantIdinteger
partnerPaymentUniqueIdstring
Response
application/json
{
  "payeeId": 0,
  "amount": 0,
  "currency": "string",
  "paymentMethodType": "string",
  "description": "string",
  "partnerId": 0,
  "merchantId": 0,
  "partnerPaymentUniqueId": "string"
}

Search Transactions

Request

This API helps partners find payments that were created earlier. You can use it to check the latest payment status or view payment history. Only payments from merchants linked to the partner will be returned

Security
Bearer
Body
required
pageNumberinteger(int32)

Page number for paginated results (default:1).

pageSizeinteger(int32)

Number of records per page (default:10).

routestring or null

Internal route value (set automatically by the client in some flows)

sortPropertystring or null

Property name to sort results by.

isDescendingboolean
partnerIdinteger(int32)required

(Required) Partner ID to filter transactions for this partner

paymentIdinteger or null(int32)

(Optional) Specific payment ID to search for

merchantIdinteger(int32)required

(Required) Merchant ID to filter transactions for this merchant.

curl -i -X POST \
  https://docs.theropay.co/_mock/theropay/docs/reference/partners/finance/v1/partner/search_transactions \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "pageNumber": 0,
    "pageSize": 0,
    "route": "string",
    "sortProperty": "string",
    "isDescending": true,
    "partnerId": 0,
    "paymentId": 0,
    "merchantId": 0
  }'

Responses

Search completed successfully. Response contains matching transactions.

Bodyapplication/json
partnerIdinteger
paymentIdinteger
merchantIdinteger
pageNumberinteger
pageSizeinteger
Response
application/json
{
  "partnerId": 0,
  "paymentId": 0,
  "merchantId": 0,
  "pageNumber": 0,
  "pageSize": 0
}