Note on Additional References

  • Tutorial: Payouts API Workflow: This tutorial guides you through the end-to-end process of using Payouts API, from setting up payee accounts to executing transactions.
  • Calculating VerifySign Values: Learn to confirm webhook authenticity through MD5 signature verification.
  • Transfer Payout API: Consult this to set the IPN URL in your request body, which is crucial for receiving webhook notifications.

Transaction Status Definitions

pendingThe payout request has been successfully received by the system. It is currently in the queue for processing. You should monitor the transaction status, as it will update once the processing is complete.
successThe transaction has been processed without any issues, and the funds have been credited to the recipient's account. No further action is required unless you have post-payment processes in place.
failedThe payout request was not completed, and the funds were not deducted from the sender's account. This could be due to various reasons such as insufficient funds, incorrect payment details, or a system error. Review the provided error details, rectify any issues, and attempt the payout again if appropriate.
returnedThe payout request was cancelled after it was initiated. This could occur if the recipient's account rejects the funds or if there's an issue with the payment method. Ensure the account and payment details are correct and contact support if you need clarification on the cancellation.

Transaction Notifications Overview

In the payout process, there are two critical notifications that you, as a developer, need to be aware of to manage and acknowledge the transactions effectively

First Notification - Transfer API Response

When you make a call to the Transfer API to initiate a payout, the immediate response will not be the final transaction status. Instead, it will indicate a 'pending' status. This 'pending' response is important as it signifies that your payout request has been received and is currently in line to be processed by Pockyt's systems, but has not yet been executed through the banking and payments system

Sample 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"
amountStringThe payment amount in the specified currency.
transactionNoStringThe unique identifier for the transaction.
createdTimeStringThe timestamp of when the transaction was created.
invoiceIdStringThe unique ID for the payment in the merchant's system.
currencyStringThe currency in which the payment is made.
accountTokenStringThe funding source account token, generated by Pockyt.
customerNoStringThe payee's ID in the Pockyt system.
statusStringThe status of the transaction, in this case "pending".
ret_msgStringThe message describing the API call result.
ret_codeStringThe code representing the result of the API call.

Second Notification - Pockyt Webhook to IPN Url

The final outcome of your payout request will be communicated through a webhook. Unlike the initial API response, this is an asynchronous notification that will be sent to a URL specified by you, known as the IPN (Instant Payment Notification) URL. This IPN URL needs to be a part of your initial request payload to the Transfer API. Once the payout is processed, Pockyt will send a POST request to your IPN URL with the final status of the payout - whether it was successful, failed, or encountered any errors.

To successfully receive and handle these notifications, you must ensure that the IPN URL provided in your API call is configured to accept POST requests and can process the incoming webhook data. Properly handling these notifications is crucial for maintaining an up-to-date record of transaction statuses and for implementing any post-transaction logic in your application.

Sample Response:

    "accountToken": "2010300192540133960288",
    "amount": "60.00",
    "currency": "USD",
    "invoiceId": "9aae4c685d824c5da746f97620c59ec7",
    "paymentTime": "2023-02-15T22:59:11Z",
    "status": "success",
    "transactionNo": "318453016214317262",
    "vendor": "BANK_ACCOUNT",
    "verifySign": "0cc4979fceb164797c6bac54132c90e0"
accountTokenStringThe funding source account token, provided by Pockyt.
amountStringThe total amount transferred in the specified currency.
currencyStringThe currency code of the payment amount.
invoiceIdStringA unique identifier for the payment within the merchant's system.
paymentTimeStringThe exact timestamp when the payment was processed.
statusStringThe status of the transaction; refer to the Appendix for possible values.
transactionNoStringPockyt's unique identifier for the transaction.
vendorStringThe method used for the transfer, such as 'BANK_ACCOUNT'.
verifySignStringAn MD5 signature hash of the notification request for verifying its authenticity.