Guides

Payouts to Chinese Bank Accounts

This guide details a step-by-step implementation of payouts to Chinese bank accounts via the non-Pockyt wallet configuration.

Suggest Edits

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 solutions@pockyt.io 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 solutions@pockyt.io or contact your sales representative.

API Diagram

API workflow

📘

API References for Endpoints in this Workflow:

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.
    • This accountToken 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

  1. 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.

  2. 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).

  3. Webhook Management:

    • IPN URL: Receives asynchronous notifications on payout status.
    • Ensure webhook validation of transactionNo and status.

Updated 11 days ago