Payouts to Chinese Bank Accounts

Introduction

This guide covers how to use Integrated Payouts to use Chinese bank accounts with the non-Pockyt wallet configuration. For other configurations, payout methods, and currencies, please contact the solutions team at [email protected] to get setup.

🚧
Prerequisites

Merchant Account Setup – Ensure the merchant has an active Pockyt account.

API Credentials – Obtain merchantNo, storeNo values from Pockyt.

Webhook Configuration – Set up ipnUrl to receive transaction status updates.

Banking Requirements – Ensure the payee’s bank supports ACH transfers.

Regulatory Compliance – Merchants must adhere to Know Your Customer (KYC) and Anti-Money Laundering (AML) regulations. It is important that the merchant has been approved by Pockyt's compliance team for this service. If you have any questions, reach out to [email protected] or contact your sales representative.

API Diagram

API workflow

📘
API References for Endpoints in this Workflow:

Step 1 Register Payee /v1/customers/create

Step 2 Query payee status /v3/payee/retrieve

Step 3 Retrieve bank account configurations

Step 4 Add bank account as Payout mehtod

Step 4 Query payee funding account /v3/process

Step 5 Transfer payouts

Step-by-Step Description of the Recurring Payments Workflow

Step 1: Register Payee

Action: The Merchant Backend calls the Register Payee API to create a new payee in the Pockyt system. This step generates a unique customerNo, which will be used in subsequent steps for identifying the payee.
Endpoint: POST /v3/payee/register
Key Considerations:
- The profileType (INDIVIDUAL or BUSINESS) determines the required fields.
- The payee’s email and governmentId must be unique.
- The customerNo returned here is needed in Step 5 and Step 6.

Step 2: Submit Payee Documentation

Action: The Merchant submits required documentation to Pockyt's support team to verify the payee's identity and ensure regulatory compliance.

Key Considerations:

Payee accounts are initially set to ACTIVE upon creation. However, certain trigger events in compliance reviews may change their status to PENDING or DECLINED.
It is crucial for the merchant to verify the payee’s status before initiating a payout to ensure funds are not sent to an ineligible payee.

Step 3: Query Payee Status

Action: The Merchant Backend calls the Query Payee Status API to verify if the payee is fully verified and eligible to receive payouts.
Endpoint: POST /v3/payee/retrieve
Key Parameters:
- Request Body: Includes customerNo to retrieve the payee’s current status.
- Response: payee details, including profileType, payeeStatus, firstName, lastName, email, etc.

Step 4: Retrieve Bank Account Configurations

Action: The Merchant Backend calls the Account Configuration API to retrieve available payment method configurations for international transfers
Endpoint: POST /v3/payee/account/configurations
Key Considerations:
- This is a data service for developers, ensuring they retrieve the most up-to-date banking requirements for different countries and currencies.
- The international banking system is in constant flux, with compliance requirements varying based on jurisdiction and regulation.
- Pockyt provides this service so developers always have access to the correct fields needed to register a payee’s bank account without requiring manual updates

[
  {
    "profileType": "INDIVIDUAL",
    "accountType": "BANK_ACCOUNT",
    "accountCurrency": "CNY",
    "accountCountry": "CN",
    "fields": [
      {
        "isRequired": true,
        "minLength": 8,
        "name": "cardNumber",
        "label": "Card Number",
        "maxLength": 32
      },
      {
        "isRequired": true,
        "minLength": 8,
        "name": "bankCode",
        "label": "Bank Code",
        "maxLength": 8
      },
      {
        "isRequired": true,
        "minLength": 8,
        "name": "governmentId",
        "label": "Govenment ID",
        "maxLength": 64
      },
      {
        "isRequired": true,
        "minLength": 6,
        "name": "governmentIdType",
        "label": "Govenment ID Type",
        "maxLength": 32
      }
    ]
  }
]

Step 5: Add Bank Account as a Payout Method

Action: The Merchant Backend calls the Create Bank Account API to link a bank account as a payout method for a payee.
Endpoint: POST /v3/payee/account/create/bank-account
Key Considerations:
- The customerNo from Step 1 is required in this request.
- Bank Account Name must match the payee’s name exactly to avoid rejection.
- Ensure accountType is set correctly (CHECKING or SAVINGS).
- The response returns an accountToken, which serves as the payment token for this payout method.
- ThisaccountToken must be included in Step 6 to execute the payout.
- Example accountToken: `2010378298556879970563

Step 6: Query Payee Funding Accounts

Action:The Merchant Backend calls the Query Payee Funding Accounts API to retrieve the payee’s payout accounts.
Endpoint: POST /v3/payee/payout-accounts
Key Parameters:
- Query Parameters:
  - accountToken (optional) – if provided, retrieves details of the specific account associated with the token; if omitted, returns all accounts linked to the payee.
- Response: Returns the list of payout accounts associated with the payee.

Step 7: Transfer Payout

Action: The Merchant Backend initiates a payout to a payee’s account.
Endpoint: POST /v3/payouts/pay
Key Parameters:
- Request Body:Includes accountToken, customerNo, amount, currency, invoiceId, and optional parameters such as ipnUrl, processingChannel, memo, etc.
- Response: Returns transaction details, including transactionNo, status, amount, currency, etc.

Key Considerations:

The customerNo from Step 1 and the accountToken from Step 5 are required.
Ensure amount does not exceed the merchant’s available balance.
The invoiceId should be unique to avoid duplicate payouts.
The ipnUrl is critical for receiving transaction updates.

🚧
Remember

This API request only confirms Pockyt received the payout request—it does not confirm that the funds have been deposited.

The actual payout status must be checked via webhook notifications, as banking transactions process asynchronously.

Step 8: Handle Webhook Notification for Recurring Payments

Action: The webhook is triggered once the customer accepts the billing agreement in the checkout UI. However, the payment method has not been charged yet.
Purpose: The webhook contains the transactionNo, which is required for charging the payment method in the next step via the /process API. It also includes the vaultId, which should be saved for future use, though it is not fully activated until the /process API is called.
See Example Webhook Notification Body Here

Key Notes for Implementation

Parameters Flow:
- customerNo: Generated in payee registration (Step 1), required for all subsequent steps.
- transactionNo: Generated in payout initiation (Step 7), used to track the transaction.
- payeeStatus: Retrieved from /v3/payee/retrieve (Step 3) to verify payee eligibility.
API Endpoints:
- /v3/payee/register: Register payees (Step 1).
- /v3/payee/account/create: Add bank account payout method (Step 5).
- /v3/payouts/pay: Initiate payout (Step 7).
Webhook Management:
- IPN URL: Receives asynchronous notifications on payout status.
- Ensure webhook validation of transactionNo and status.