Payor Onboarding via API

Introduction

This guide walks Merchant of Record (MoR) integrations through the process of onboarding Payors (sub-merchants) programmatically using the Pockyt API. Instead of registering Payors manually through the Pockyt Portal, the MoR can automate the process using two endpoints.

The onboarding workflow has two key functions:

1. Register Payor: The MoR backend submits the Payor's business information, representative details, and banking data to Pockyt. Pockyt returns a payorNo that identifies the Payor across all subsequent payout operations.
2. Upload Documents: The MoR backend uploads the Payor's verification documents (business license, government ID, bank statements, etc.) using the payorNo. Pockyt's compliance team reviews the submission and approves or declines the Payor.

Once approved, the MoR can register payees, create funding accounts, and execute payouts on behalf of that Payor using the standard payout endpoints with the payorNo parameter.

🚧

Pre-requisites

MoR Account: You must have an active Merchant of Record account with Pockyt. Your account must be in APPROVED or EFFECTIVE status and have the MoR merchant type enabled.

API Credentials: Obtain merchantNo, storeNo, and your API token from Pockyt. These are the same credentials used across all Pockyt payout endpoints.

Document Preparation: Have your Payor's verification documents ready before starting — at minimum a business license and a government-issued ID for the representative. See Supported Document Types for the full list.

API Diagram

sequenceDiagram
    participant MB as MoR Backend
    participant PA as Pockyt API
    participant PC as Pockyt Compliance

    Note over MB: Step 1: Register Payor
    MB->>PA: POST /v1/payor/register
    PA-->>MB: payorNo, status: SUBMITTED

    Note over MB: Step 2: Upload Documents
    MB->>PA: POST /v1/payor/upload/{payorNo}
    PA-->>MB: Upload confirmation
    MB->>PA: POST /v1/payor/upload/{payorNo} (repeat per document)
    PA-->>MB: Upload confirmation

    Note over PC: Compliance Review
    PC-->>PA: Payor status updated (APPROVED / DECLINED)

API workflow

📘

API References for Endpoints in this Workflow:

• Step 1 Register Payor
• Step 2 Upload Payor Document

Step-by-Step Payor Onboarding Workflow

Step 1: Register Payor

Action: The MoR backend submits the Payor's business and representative information to Pockyt, which returns a payorNo identifying the new Payor.

1. The MoR backend calls the POST /v1/payor/register endpoint with the Payor's business details, DBA address, bank information, representative information, and payment settings.
2. Authentication uses the standard verifySign signature — the same MD5-based signing method used across all Pockyt payout endpoints.
3. On success, the response includes a payorNo and a status of SUBMITTED. The payorNo is permanent and will be used in Step 2 and in all future payout operations for this Payor.

⚠️

Important: The email and legalName must be unique across all Payors. If either is already registered, the API returns an error. Plan your Payor data accordingly before submitting.

Step 2: Upload Documents

Action: The MoR backend uploads the Payor's verification documents using the payorNo returned in Step 1.

1. The MoR backend calls the POST /v1/payor/upload/{payorNo} endpoint for each document. Authentication parameters (merchantNo, storeNo, timestamp, verifySign) and the fileType are sent as query parameters. The file itself is sent as multipart/form-data in the request body.
2. Each call uploads a single document. Repeat the call for each required document type — at minimum, upload a businessLicense and an issuedId for the representative.
3. Files must be under 10 MB. Supported formats include PDF, JPEG, PNG, DOC/DOCX, and XLS/XLSX.

📘

Note: The file content is excluded from the verifySign signature calculation. Only the query parameters (merchantNo, storeNo, payorNo, timestamp, fileType, and optionally fileName) participate in the signature.

After Submission

Once both steps are complete, the Payor application enters Pockyt's compliance review queue. The review includes underwriting, risk assessment, and document verification. Payor status progresses through these stages:

Once the Payor reaches APPROVED status, you can begin the payout flow: register payees with the payorNo, create funding accounts, and execute payouts. See Direct Merchant vs. MoR Payouts for a full explanation of how payorNo is used across the payout endpoints.

Supported Document Types

⚠️

Important: Contract documents cannot be uploaded via API. Contracts must be uploaded directly in the Pockyt Portal by the MoR.

Key Considerations

1. Same Credentials, Different Auth Method: Unlike the Merchant Onboarding API (which uses OAuth bearer tokens), Payor onboarding uses the standard verifySign MD5 signature — the same authentication method used across all Pockyt payout endpoints. No separate token step is needed.

2. Portal Alternative: Payors can also be registered manually through the Pockyt Portal. The API flow described here is for MoRs that want to automate onboarding at scale.

3. Error Handling: A ret_code of 000100 indicates success on all Pockyt API responses. Common registration errors include 000022 (email already in use) and 000023 (legal name already in use). Handle errors consistently and implement retry logic for transient failures.