Synchronous and Asynchronous Notifications

In Pockyt's API system, particularly for the Pay-Ins products, merchants interact with both synchronous and asynchronous notifications, which are crucial for understanding the transaction flow.

Synchronous Notifications

When a merchant makes an API call, they receive an immediate, synchronous response from Pockyt. This response indicates that Pockyt has successfully received the request and has forwarded it to the payment network for processing. In most cases, the initial transaction status received in this synchronous response will be "successful" or "pending."

For example, consider an in-store payment scenario where the customer presents a mobile device to be scanned. The merchant makes an API call like this:

curl -XPOST -H "Content-type: application/json" -d '{ 
    "merchantNo": "200043",
    "storeNo": "300014",
    "verifySign": "f38965887c5676e2fb19d951251eb613", 
    "transactionNo": "297553636764407286", 
    "paymentBarcode": "286498530672949108",
    "vendor": "alipay"
}' 'https://mapi.yuansfer.com/app-instore/v3/pay'

The merchant POS can expect a response like:

{
    "result": {
        "amount": "13.00",
        "createTime": "2020-10-12 21:38:16",
        ...
        "transactionStatus": "pending",
        ...
    },
    "ret_code": "000100",
    "ret_msg": "add success"
}

In this response, if the transactionStatus is "pending," it indicates that the customer still needs to confirm the payment in their digital wallet app.

Asynchronous Notifications and Polling Logic for In-Store Payments

For transactions that return a "pending" status, the merchant system should implement a "polling" logic, repeatedly calling the Transaction-Query API endpoint until the status updates. This is an example of asynchronous notification, where the final transaction status is not immediately known.

An example of the Transaction-Query call:

curl -XPOST -H "Content-type: application/json" -d '{
    "merchantNo": "200043",
    "storeNo": "300014",
    "transactionNo": "297553638241892410",
    "verifySign": "0df745088d7202a6d186596acdc82c6a"
}' 'https://mapi.yuansfer.com/app-data-search/v3/tran-query'

Once the customer confirms the payment, and the transaction status changes to "successful," the POS system can then proceed to the next step, confirming the payment completion to the cashier.

A successful transaction response:

{
    "result": {
        "amount": "10.00",
        "currency": "CNY",
        ...
        "status": "success",
        ...
    },
    "ret_code": "000100",
    "ret_msg": "query success"
}

In summary, understanding the synchronous and asynchronous notifications in Pockyt's API is crucial for handling different transaction scenarios effectively, especially in managing the flow from payment initiation to final confirmation.

Asynchronous Webhooks and Instant Payment Notifications (IPN's) for Online Payments

Instant Payment Notification (IPN) is a crucial asynchronous notification mechanism used in Pockyt's Pay-Ins Solution, particularly for Online/eCommerce Payment Scenarios and potentially in in-store payment scenarios with cloud-based POS platforms or specific network security requirements.

IPN in Online Payments

When a customer at an online store selects a digital wallet for payment, the merchant's website redirects them to the Pockyt Cashier Page (in Pockyt Hosted Payments). At this point, the merchant's store initiates an API call to the SecurePay endpoint, specifying an "ipnURL". This URL is the "listener page" created by the merchant to receive asynchronous notifications.

An example of a SecurePay API call:

curl -XPOST -H "Content-type: application/json" -d '{
    "merchantNo": "200043",
    "storeNo": "300014",
    ...
    "ipnUrl": "http://zk-tys.yunkeguan.com/ttest/test",
    ...
}' 'https://mapi.yuansfer.com/online/v3/secure-pay'

The response to this call might look like this:

{
    "result": {
        "amount": "13.00",
        "cashierUrl": "http://zk-tys.yunkeguan.com/appTransaction/yuansfer-redirect-record/297553638298245023",
        ...
    },
    "ret_code": "000100",
    "ret_msg": "prepay success "
}

Even though the response shows "prepay success," the merchant must wait for the digital wallet service's approval before confirming the order. This is where the IPN listener page comes into play.

IPN Listener Page

Merchants create an IPN listener page on their website and specify its URL in the SecurePay API request. Pockyt API sends notifications about transaction events to this URL. The notifications are sent as secure FORM POSTs containing payment information. The IPN listener page, which contains a custom script or program, processes these messages and validates the success status. It's crucial for the IPN listener to respond with a plain text 'success' to Pockyt; otherwise, Pockyt will resend the notification up to 8 times over 2 hours.

Importance of verifySign Validation

It's recommended that merchants validate the verifySign of incoming messages from Pockyt. This parameter is included in the incoming notification messages, and its validation ensures the authenticity of the notification. Merchants can refer to the tutorial on calculating the verifySign value for outgoing calls to Pockyt and apply the reverse process for incoming messages.