Payouts API's Workflow

This section of our API documentation provides a concise walkthrough of the Pockyt Payout API's workflow. As you integrate this functionality into your application, you will engage with a sequence of steps that ensure both the setup and the execution of payouts are seamless and secure.

📘

Key Resources for Payouts API**

• Full List of Payouts API's: A catalog of available APIs, detailing their roles in payment processing.
• Transaction Notifications Reference: Insights on the alerts you'll receive regarding payout statuses.
• Response and Status Code Definitions: A guide to understanding the meanings behind various API response codes.

Payouts API Workflow Tutorial

This tutorial outlines the typical steps involved in the workflow of Pockyt's Payouts service. The process encompasses everything from registering a payee to executing a payout and managing subsequent notifications.

1. Registering a Payee:

   • The first step involves adding a payee to the system. This process includes creating a unique identifier for the payee, known as a customerNo.

2. Adding a Payout Method:

   • Once the payee is registered, the next step is to associate a bank account or another applicable payment method with them. This is identified in the system as an accountToken.

3. Executing a Payout:

   • With the payee and their payout method set up, the next phase is to initiate the actual payout transaction.

4. Handling Notifications:

   • The final step involves managing asynchronous notifications to keep track of the payout status.

This workflow provides a clear and concise overview of the essential steps required to effectively utilize Pockyt's Payouts API, from the initial setup to the execution and monitoring of payouts.

Step 1: Register Payee Account

📘

Register Payee API Reference

To begin the payouts process, the first step is to register the payee by calling the Pockyt API endpoint "Register Payee." Send a POST request to this endpoint:

https://mapi.yuansfer.com/v3/payee/account/create/bank-account

Upon successful registration, you will receive a unique customer number (customerNo) in the response. This customer number is essential for initiating payments to your payees through Pockyt.

Request

curl -X POST https://mapi.yuansferdev.com/v3/payee/register \
-H "Content-Type: application/json" \
-d '{
    "city": "hometown",
    "country": "USA",
    "countryCode": "US",
    "customerCode": "1665425422",
    "dateOfBirth": "1999-01-01",
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "merchantNo": "202333",
    "phone": "1234567890",
    "profileType": "INDIVIDUAL",
    "state": "NY",
    "storeNo": "301854",
    "street": "123 main St",
    "street2": "",
    "timestamp": "2023-02-13T10:50:58Z",
    "verifySign": "2e2294120492ca91b0be1db9a3c98c0e",
    "zip": "10005"
}'

Response

{
    "ret_msg": "success",
    "ret_code": "000100",
    "customer":
    {
        "firstName": "John",
        "lastName": "Doe",
        "customerCode": "1665425422", //Save this Value
        "createdTime": "2022-10-10T18:15:19Z",
        "customerNo": "2000305228292319592008",
        "email": "[email protected]"
    }
}

Step 2: Register Payee Payout Method

📘

Register Payout Method API Reference

To add a new payout method, like a bank account, for a payee, you can use the Pockyt API endpoint "Add Payee Bank." Send a POST request to the following URL:

https://mapi.yuansfer.com/v3/payee/account/create/bank-account

To use this endpoint, you need to include your Merchant ID and payment details in the request. This ensures secure linking of a new bank account to the designated payee for smooth payouts.

Request

curl -X POST https://mapi.yuansfer.com/v3/payee/account/create/bank-account \
-H "Content-Type: application/json" \
-d '{
    "accountCountry": "US",
    "accountCurrency": "USD",
    "accountTag": "1a52692711",
    "bankAccountId": "7861053298",
    "branchId": "101089292",
    "accountType": "BANK_ACCOUNT",
    "bankAccountPurpose":"CHECKING",
    "customerNo": "2000305228303182610217",
    "ipnUrl": "https://example.com/webhooks",
    "merchantNo": "202333",
    "storeNo": "301854",
    "timestamp": "2023-02-13T11:50:58Z",
    "clientIp":"127.0.0.1",
    "verifySign": "23f56c32ddcd8732eced87f139d086d9"
}'

Response

{
    "result": {
        "accountTag": "1a52692711",
        "accountStatus": "ACTIVATED",
        "country": "US",
        "firstName": "John",
        "lastName": "Doe",
        "accountType": "BANK_ACCOUNT",
        "currency": "USD",
        "accountToken": "2010305228303182765718",
        "customerNo": "2000305228292319592008",
        "email": "[email protected]",
        "timestamp": "2023-02-13T11:48:12Z"
    },
    "ret_msg": "success",
    "ret_code": "000100"
}

Step 3: Execute Payout Transfer

To initiate a transfer after setting up a payee account and registering their payout method, you'll need to make a POST request to the payouts API. Use the following endpoint to send your transfer request:

https://mapi.yuansfer.com/v3/payouts/pay

The API will process this request and execute the transfer accordingly.

Transaction Results and Asynchronous Notifications

The responses to the Transfer API call are asynchronous, which means that the final result of your payout transaction won't be available immediately. Instead, when you make your initial API request, you must include an "IPN URL" (Instant Payment Notification URL). This is the endpoint where Pockyt will send a POST request with the final status of your payout transaction once it has been processed.

Here's what happens step by step:

• You send the initial POST request to the Transfer API.
• The API responds to confirm receipt of your transfer request. At this point, if everything is in order, you'll receive a response message indicating a "successful" operation with a status code "000100".
• However, within the response payload, the "status" parameter will be marked as "pending". This status indicates that your payout transfer request has been acknowledged by the system and is now queued for processing.

The "pending" status is an intermediate confirmation — it means that the API has received your request and it is in line to be processed. The actual completion of the transfer, whether it is successful or not, will be communicated to you via a POST message to the IPN URL you provided. Once Pockyt processes your payout request, it will send a notification to this URL with the final transaction status, allowing your system to update the payment status accordingly. For an explanation of the full list of parameter values included in the asynchronous notification, please follow the link below:

📘

Asynchronous Transaction Notification Reference

Request

curl -X POST https://mapi.yuansfer.com/v3/payouts/pay \
-H "Content-Type: application/json" \
-d '{
    "accountToken": "2010305228303182765718",
    "amount": "500",
    "currency": "USD",
    "customerNo": "2000305228292319592008",
    "description": "thank you",
    "invoiceId": "9aae4c685d824c5da746f97620c59eb5",
    "ipnUrl": "https://example.com/webhooks",
    "merchantNo": "202333",
    "note": "Cold drink",
    "storeNo": "301854",
    "subject": "Payouts",
    "timestamp": "2023-02-13T11:58:58Z",
    "verifySign": "8b11e8f0d7f2a412f020f266110b57ba"
}'

Response

{
    "result": {
        "amount": "500.00",
        "transactionNo": "305588797074336092",
        "createdTime": "2023-02-13T11:58:59Z",
        "invoiceId": "9aae4c685d824c5da746f97620c59eb5",
        "currency": "USD",
        "accountToken": "2010305228303182765718",
        "customerNo": "2000305228303182610217",
        "status": "pending"
    },
    "ret_msg": "succeeded",
    "ret_code": "000100"
}

Asynchronous Transaction Notification Body:

{
    "accountToken": "2010300192540133960288",
    "amount": "60.00",
    "currency": "USD",
    "invoiceId": "9aae4c685d824c5da746f97620c59ec7",
    "paymentTime": "2023-02-15T22:59:11Z",
    "status": "success",
    "transactionNo": "318453016214317262",
    "vendor": "BANK_ACCOUNT",
    "verifySign": "0cc4979fceb164797c6bac54132c90e0"
}