📘
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

Value	Description
pending	The 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.
success	The 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.
failed	The 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.
returned	The 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"
}

Parameter	Type	Description
amount	String	The payment amount in the specified currency.
transactionNo	String	The unique identifier for the transaction.
createdTime	String	The timestamp of when the transaction was created.
invoiceId	String	The unique ID for the payment in the merchant's system.
currency	String	The currency in which the payment is made.
accountToken	String	The funding source account token, generated by Pockyt.
customerNo	String	The payee's ID in the Pockyt system.
status	String	The status of the transaction, in this case "pending".
ret_msg	String	The message describing the API call result.
ret_code	String	The 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"
}

Parameter	Type	Description
accountToken	String	The funding source account token, provided by Pockyt.
amount	String	The total amount transferred in the specified currency.
currency	String	The currency code of the payment amount.
invoiceId	String	A unique identifier for the payment within the merchant's system.
paymentTime	String	The exact timestamp when the payment was processed.
status	String	The status of the transaction; refer to the Appendix for possible values.
transactionNo	String	Pockyt's unique identifier for the transaction.
vendor	String	The method used for the transfer, such as 'BANK_ACCOUNT'.
verifySign	String	An MD5 signature hash of the notification request for verifying its authenticity.