Merchant of Record Payout Workflow

Introduction

This guide covers how a Merchant of Record (MoR) executes payouts to bank accounts on behalf of a Payor (sub-merchant). It follows the same payout endpoints used by Direct Merchants — the only difference is that the MoR includes the payorNo parameter when registering payees and creating funding accounts, which associates those entities with the correct Payor.

If you haven't onboarded your Payor yet, start with the Payor Onboarding via API guide first. You need an approved payorNo before proceeding.

The MoR payout workflow has four key functions:

1. Register Payee: The MoR registers a payee and associates them with a Payor by including payorNo in the request. This is the step where the Payor–payee relationship is established — it cannot be changed after registration.
2. Retrieve Bank Configuration: The MoR queries the required fields for the payee's target bank account country and currency to ensure the correct parameters are submitted in the next step.
3. Create Funding Account: The MoR creates a bank account for the payee, again including payorNo to maintain the Payor association at the account level.
4. Execute Payout: The MoR initiates a payout to the payee's funding account. No payorNo is needed here — the system resolves the Payor context automatically from the payee and account relationship.

🚧

Pre-requisites

MoR Account: You must have an active Merchant of Record account with Pockyt.

API Credentials: Obtain merchantNo, storeNo, and your API token from Pockyt.

Approved Payor: Your Payor must be registered and in APPROVED status with a valid payorNo. See Payor Onboarding via API.

Webhook Configuration: Set up ipnUrl to receive asynchronous payout status updates.

API Diagram

sequenceDiagram
    participant MB as MoR Backend
    participant PA as Pockyt API

    Note over MB: Step 1: Register Payee (with payorNo)
    MB->>PA: POST /v3/payee/register
    PA-->>MB: customerNo

    Note over MB: Step 2: Retrieve Bank Configuration
    MB->>PA: POST /v3/payee/account/configurations
    PA-->>MB: Required fields for country/currency

    Note over MB: Step 3: Create Funding Account (with payorNo)
    MB->>PA: POST /v3/payee/account/create/bank-account
    PA-->>MB: accountToken

    Note over MB: Step 4: Execute Payout
    MB->>PA: POST /v3/payouts/pay
    PA-->>MB: transactionNo, status: processing

    Note over PA: Webhook Notification
    PA-->>MB: Final payout status (settled / failed)

API workflow

📘

API References for Endpoints in this Workflow:

• Step 1 Register Payee
• Step 2 Retrieve Bank Configuration
• Step 3 Create Funding Account
• Step 4 Execute Payout
• Webhook Notification Reference

Step-by-Step MoR Payout Workflow

Step 1: Register Payee

Action: The MoR registers a payee in Pockyt and associates them with a specific Payor by including payorNo in the request.

1. The MoR backend calls the POST /v3/payee/register endpoint with the payee's personal information (firstName, lastName, email, governmentId, dateOfBirth, etc.) and includes the payorNo of the Payor this payee belongs to.
2. The profileType parameter determines the required fields — use INDIVIDUAL for persons or BUSINESS for companies.
3. On success, Pockyt returns a customerNo that identifies this payee across all subsequent steps.

⚠️

Important: The payorNo association is permanent. Once a payee is registered under a Payor, it cannot be reassigned. Make sure the correct payorNo is used at registration time.

Step 2: Retrieve Bank Configuration

Action: The MoR queries the required fields for creating a bank account in the payee's target country and currency.

1. The MoR backend calls the POST /v3/payee/account/configurations endpoint, specifying the target accountCountry, accountCurrency, and accountType.
2. The response returns the exact fields required for that country/currency combination — field names, labels, min/max lengths, and whether each field is required.
3. Use these fields to build the request for Step 3. Banking requirements vary by jurisdiction and can change, so always query this endpoint before creating an account rather than hardcoding field lists.

Step 3: Create Funding Account

Action: The MoR creates a bank account for the payee, including payorNo to maintain the Payor association at the account level.

1. The MoR backend calls the POST /v2/payee/account/create/bank-account endpoint with the customerNo from Step 1, the payorNo, and the bank account fields retrieved in Step 2.
2. The bank account holder name must match the payee's registered name exactly to avoid rejection.
3. On success, the response returns an accountToken — this is the payment token used in Step 4 to execute the payout.

Step 4: Execute Payout

Action: The MoR initiates a payout to the payee's funding account.

1. The MoR backend calls the POST /v3/payouts/pay endpoint with the customerNo from Step 1 and the accountToken from Step 3.
2. No payorNo is needed in this request — Pockyt resolves the Payor context automatically from the payee and account relationship established in the previous steps.
3. The response confirms that the payout request was received with a transactionNo and a status of processing. This does not mean funds have been delivered — payout settlement is asynchronous.

✅

Payouts should only be considered complete after a "settled" status is received via webhook. The API response in this step only confirms Pockyt has accepted the request.

Handle Webhook Notifications

Action: Pockyt sends a webhook to the MoR backend with the final payout result.

• The webhook includes the transactionNo, final status (settled or failed), amount, and currency.
• The MoR should listen for this webhook on the URL defined in the ipnUrl parameter of the payout request.
• For MoR payouts, the webhook response also includes the payorInfo object confirming which Payor the transaction belongs to.

What Changes for MoR vs. Direct Merchant

The endpoints, parameters, and flow are identical to the Direct Merchant payout workflow. The only differences are:

For a full explanation of the MoR entity model and how payorNo works across the platform, see Direct Merchant vs. MoR Payouts.

Key Considerations

1. Payor Association is Set at Two Points: payorNo is passed explicitly in Step 1 (Register Payee) and Step 3 (Create Funding Account). After that, the Payor context travels implicitly — payout initiation and queries resolve the Payor from the payee/account relationship. Neither can be changed after creation.

2. Account Deletion Restrictions: Deleting a funding account under the MoR model is subject to Payor status validation. Accounts tied to a Payor with a DECLINED or SAVED status cannot be deleted.

3. Error Handling: A ret_code of 000100 indicates success on all Pockyt API responses. Handle errors consistently and implement retry logic for transient failures.