Guides
Start typing to search…

Payouts to Paypal wallet

This guide details a step-by-step implementation of payouts using the Paypal Wallet.

Introduction

This guide covers how to use Integrated Payouts to use Paypal 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 Workflow

Step-by-Step Breakdown of the Payout Workflow

📘

API References for Workflow Steps

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 4, 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: Add Paypal Payout Method

  • Action: The Merchant Backend calls the Create API to link a bank account as a payout method for a payee.
  • Endpoint: POST /v3/payee/account/create/paypal
  • 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 (PAYPAL ).
    • 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 5: 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 6: 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 4 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 7: 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.
  • 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/paypal: Add bank account payout method (Step 4).
    • /v3/payouts/pay: Initiate payout (Step 6).

  3. Webhook Management:

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

Updated 5 months ago