Introduction

Register and verify Payors (sub-merchants) programmatically under a Merchant of Record (MoR) account. Instead of onboarding Payors manually through the Pockyt Portal, MoR integrations can automate the process using two API endpoints.

The onboarding workflow involves two key functions:

Register Payor: Submit 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.
Upload Documents: Upload 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.

🚧
Pre-requisites
MoR Account: You must have an active Merchant of Record account with Pockyt in APPROVED or EFFECTIVE status.
API Credentials: Obtain merchantNo, storeNo, and API token values from Pockyt.
Authentication: All API requests must include a valid verifySign. See Signing API Calls for details.
Document Preparation: Have the Payor's verification documents ready before starting — at minimum a business license and a government-issued ID for the representative.

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: Repeat per document type
    PA-->>MB: Upload confirmation

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

How Payor Onboarding Works

The onboarding flow is straightforward:

Register the Payor by calling POST /v1/payor/register with the Payor's business details, DBA address, bank information, representative information, and payment settings. The response includes a payorNo and a status of SUBMITTED.
Upload verification documents by calling POST /v1/payor/upload/{payorNo} for each required document. Each call uploads a single file as multipart/form-data. At minimum, upload a businessLicense and an issuedId.
Pockyt reviews the application. The Payor progresses through SUBMITTED → PENDING → APPROVED (or DECLINED). Once approved, you can register payees, create funding accounts, and execute payouts using the payorNo.

📘
API References:

Register Payor

Upload Payor Document

Key Considerations

Unique Constraints: The email and legalName fields must be unique across all Payors. If either is already registered, the API returns an error. Plan your Payor data accordingly before submitting.
Payor Association is Permanent: Once a payorNo is issued, it permanently identifies the Payor across all payout operations. Payees registered with a payorNo cannot be reassigned to a different Payor.
Portal Alternative: Payors can also be registered manually through the Pockyt Portal. The API flow is for MoRs that need to automate onboarding at scale.
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). See Status & Error Codes for the complete reference.

Integration Guides

📘
Payor Onboarding Integration Guides:

Payor Onboarding via API

Direct Merchant vs. MoR Payouts