# Theropay Partner Integration Guide

This document provides a complete overview of how **Integration Partners** onboard into the Theropay Platform, obtain API credentials, authenticate using OAuth2 Client Credentials, and begin interacting with core APIs such as creating Payees, submitting Payment Requests, managing Payment Status, and configuring Webhooks.

## 1. Partner Account Creation

### 1.1 Apply for a Partner Account

Partners begin by visiting the Theropay portal and selecting:

> **Apply for Partner Account**


They complete a short application form.
Once submitted, the application enters **Compliance review**.

## 2. Compliance Review & Approval

Theropay’s Compliance Team reviews all partner applications.

When approved:

- The partner’s account becomes active
- No notification emails are sent
- The partner may now sign in using their **email** and **password** created during signup
- Compliance will also link the appropriate Merchants to the Integration Partner.
Partners can access and operate only on merchants assigned to them.


## 3. Logging In & Accessing the Partner Portal

After approval, partners log into the **same portal** with:

- **Email**
- **Password**


Once logged in, partners have access to:

- **API Credentials** section
- **Merchants linked to Partners**
- **Webhook Configuration**


## 4. Generating Client ID & Client Secret

Partners generate API credentials directly in the Portal.

### 4.1 Credential Generation Process

- Click **Generate Client Credentials**
- A **Client ID** and **Client Secret** are generated
- The Client Secret is **displayed only once**
- Partners must store the secret securely


If the partner loses the secret, they may click:

> Click **Regenerate Secret**
→ Old secret becomes invalid and a new one is created


## 5. API Authentication(OAuth2 Client Credentials)

Theropay uses **OAuth2 Client Credentials Flow** for server-to-server authentication.

Partners exchange:

- **Client ID**
- **Client Secret**


for an Access Token, which is then included in authorization headers for all API calls.

To obtain:

- **Access Token**


## 6. Working With Merchants & Payees (Counterparties)

Integration Partners manage only merchants that Compliance has assigned to them.

### 6.1 Creating a Payee (Counterparty)

To create a Payee on behalf of a merchant,Partners call: `POST /finance/v1/counterparty`

- Counterparties are payees belonging to a merchant, not to the partner
- Validation and onboarding rules are handled internally
- Theropay does not perform external bank account validation at this stage.


## 7. Creating a Payment Request

To initiate a payout from an assigned merchant, partners call:

`POST /finance/v1/payment_request`

The initial Payment Status follows internal logic; statuses include:

- Partner Funds Pending
- Pending
- Posted


Money movement occurs **once per day** through internal batch processes.
API response structure will be documented separately.

## 8. Checking Payment Status

Partners retrieve the status of submitted payments using:

`POST /finance/v1/partner/search_transaction`

Search filters and response formats are defined in the API documentation.

## 9. Webhook Management

Theropay sends webhook events for **Payment Status updates**.

### 9.1 Webhook Setup

- Webhook URL is configured in the **UI portal only**
- Partners receive a **Webhook Secret** (shown once)
- They must store it securely and use it to verify request signatures
- There is **no retry mechanism currently.**


Webhook payload structure is provided in the Webhook API documentation

## 10. Environments

Theropay provides two environments:

- **Development**
- **Production**


Each environment has distinct:

- Base URLs
- Client IDs
- Client Secrets


| Environment | Purpose | Credentials |
|  --- | --- | --- |
| Development | Partner testing | Separate Client ID/Secret |
| Production | Live transactions | Separate Client ID/Secret |


- **Base URLs differ per environment**
- Credentials **are not shared** across environments
Partners test first in **Development**, then switch to **Production** once approved.