Order Status Callback Interface Specification

Specification Description

Callback interface definition: It is the callback interface address passed in when the merchant places an order in the background. And the callback interface must receive parameters according to the following "Request Parameters".

Callback interface function: When an order ends (successfully or fails), TopPay will send a POST request to the merchant's background to notify information such as the order status change.

Callback interface constraint: After receiving the request, the merchant's background needs to return the string "success". Otherwise, TopPay will consider the callback to have failed.

Special Notes

Callback interface verification: After receiving the request, the merchant's background needs to verify the signature using the platform's public key. Only when the verification passes can it be considered a legitimate request and business processing can be carried out.

Verification signature details: When formatting parameters, null and empty strings need to be filtered. For details, please see the TopPaySignUtil#paramFormat method code implementation.

The sample code given below is for reference only. Please modify it according to the actual situation.

Click to get the code example of TopPaySignUtil

import java.util.HashMap;
import java.util.Map;
// import TopPaySignUtil;

public class CallBack {
    // The platform public key comes from the merchant's background
    private static final String PLAT_PUBLIC_KEY = "MIGfMA0GCSqGSIb3DQEBAQUACahEnlP3aRj8yCT+WHzR+VvPBTw9S1i7iYWb+MY09CG/HYuHF4+IxshXDJygmndxKf/esuwPybS8mAd//yubHpmZsmBqg1FffT8VH1APa6ZRWASUp4U01ZrbCCp35QA8FuWrJGMJxGx4xk7KUtV2yujxC8noQIDAQAB";  

    // Using a dictionary to receive parameters here is just an example. Please modify it according to the actual situation in actual development.
    public String callBackMethod(Map<String, String> requestParams) {
        // Note: Make sure to remove the sign field before formatting the request parameters.
        String sign = requestParams.remove("sign");

        // Format the received parameters, calculate the signature, and add the signature value to the request parameters.
        String source = TopPaySignUtil.paramFormat(requestParams);

        // Signature verification
        boolean validReq = TopPaySignUtil.verify(PLAT_PUBLIC_KEY, source, sign);
        if (!validReq) {
            // ... Signature verification error
            return "fail";
        }

        // ... Signature verification passed, execute normal business logic
        
        return "success"; // Finally, when the processing is successful, the string "success" must be returned. Otherwise, TopPay will consider the callback to have failed.
    }
}

public class TestCallBack {
    public static void main(String[] args) {
        Map<String, String> requestParams = new HashMap<>();
        requestParams.put("platOrderNum", "S820190712000002");
        requestParams.put("merchantCode", "S820211021094748000001");
        requestParams.put("orderType", "1");
        requestParams.put("orderNum", "T1231511321515");
        requestParams.put("orderAmount", "100.00");
        requestParams.put("realAmount", "99.91");
        requestParams.put("status", "30");
        requestParams.put("timestamp", "1745377181");
        requestParams.put("utr", "HDFC1234567890");
        requestParams.put("sign", "Bf8ZfHn7UyHO8TsU8Xkh2sqa0hbpKH1HSPampNXxzBn5PvJoytb8zPkHuQ...");

        // Instantiate CallBack class
        CallBack newObj = new CallBack();
        // Call the method    Output the result to the platform
        String result = newObj.callBackMethod(requestParams);
        System.out.println(result);
    }
}

<?php
require_once 'TopPaySignUtil.php';

class CallBack
{
// The platform public key comes from the merchant's background
private static $PLAT_PUBLIC_KEY = "MIGfMA0GCSqGSIb3DQEBAQUACahEnlP3aRj8yCT+WHzR+VvPBTw9S1i7iYWb+MY09CG/HYuHF4+IxshXDJygmndxKf/esuwPybS8mAd//yubHpmZsmBqg1FffT8VH1APa6ZRWASUp4U01ZrbCCp35QA8FuWrJGMJxGx4xk7KUtV2yujxC8noQIDAQAB";

    // Using an array to receive parameters here is just an example. Please modify it according to the actual situation in actual development.
    public function callBackMethod($requestParams)
    {
        // Note: Make sure to remove the sign field before formatting the request parameters.
        $sign = $requestParams["sign"];
        unset($requestParams["sign"]);

        // Format the received parameters, calculate the signature, and add the signature value to the request parameters.
        $source = TopPaySignUtil::paramFormat($requestParams);

        // Signature verification
        $validReq = TopPaySignUtil::verify(self::$PLAT_PUBLIC_KEY, $source, $sign);
        if (!$validReq) {
            // ... Signature verification error
            return "fail";
        }

        // ... Signature verification passed, execute normal business logic

        return "success"; // Finally, when the processing is successful, the string "success" must be returned. Otherwise, TopPay will consider the callback to have failed.
    }
}
// Instantiate the class
$callback = new CallBack();
$requestParams = [
    "platOrderNum" => "S820190712000002",
    "merchantCode"=>"S820211021094748000001",
    "orderType" => "1",
    "orderNum" => "T1231511321515",
    "orderAmount" => "100.00",
    "realAmount"=>"99.91",
    "status"=>"30",
    "timestamp"=>"1745377181",
    "utr"=>"HDFC1234567890",
    "sign" => "Bf8ZfHn7UyHO8TsU8Xkh2sqa0hbpKH1HSPampNXxzBn5PvJoytb8zPkHuQ...",
];
// Call the method
$result = $callback->callBackMethod($requestParams);
// Output the result to the platform
echo $result;

using System;
using System.Collections.Generic;

class CallBack
{
    // The platform public key comes from the merchant's background
    private static readonly string PLAT_PUBLIC_KEY = "MIGfMA0GCSqGSIb3DQEBAQUACahEnlP3aRj8yCT+WHzR+VvPBTw9S1i7iYWb+MY09CG/HYuHF4+IxshXDJygmndxKf/esuwPybS8mAd//yubHpmZsmBqg1FffT8VH1APa6ZRWASUp4U01ZrbCCp35QA8FuWrJGMJxGx4xk7KUtV2yujxC8noQIDAQAB";  

    // Using a dictionary to receive parameters here is just an example. Please modify it according to the actual situation in actual development.
    public string CallBackMethod(Dictionary<string, string> requestParams)
    {
        // Note: Make sure to remove the sign field before formatting the request parameters.
        string sign = requestParams["sign"];
        requestParams.Remove("sign");

        // Format the received parameters, calculate the signature, and add the signature value to the request parameters.
        var source = TopPaySignUtil.ParamFormat(requestParams);

        // Signature verification
        bool validReq = TopPaySignUtil.Verify(PLAT_PUBLIC_KEY, source, sign);
        if (!validReq)
        {
            // ... Signature verification error
            return "fail";
        }

        // ... Signature verification passed, execute normal business logic

        return "success"; // Finally, when the processing is successful, the string "success" must be returned. Otherwise, TopPay will consider the callback to have failed.
    }
}


class Program
{
    static void Main(string[] args)
    {
        // Construct the input dictionary
        var requestParams = new Dictionary<string, string>
        {
            { "platOrderNum", "S820190712000002" },
            { "merchantCode", "S820211021094748000001" },
            { "orderType", "1" },
            { "orderNum", "T1231511321515" },
            { "orderAmount", "100.00" },
            { "realAmount", "99.91" },
            { "status", "30" },
            { "timestamp", "1745377181" },
            { "utr", "HDFC1234567890" },
            { "sign", "Bf8ZfHn7UyHO8TsU8Xkh2sqa0hbpKH1HSPampNXxzBn5PvJoytb8zPkHuQ..." }
        };

        // Instantiate the CallBack class
        var newObj = new CallBack();

        // Call the method and print the result
        string result = newObj.CallBackMethod(requestParams);
        Console.WriteLine(result);
    }
}

package main

import (
    "fmt"
    // Please replace with your own utility package path
    "github.com/your-username/your-top-pay-util-package/toppayutil"
)

// CallBack defines the callback class
type CallBack struct {
    // The platform public key comes from the merchant's background
    PLAT_PUBLIC_KEY string = "MIGfMA0GCSqGSIb3DQEBAQUACahEnlP3aRj8yCT+WHzR+VvPBTw9S1i7iYWb+MY09CG/HYuHF4+IxshXDJygmndxKf/esuwPybS8mAd//yubHpmZsmBqg1FffT8VH1APa6ZRWASUp4U01ZrbCCp35QA8FuWrJGMJxGx4xk7KUtV2yujxC8noQIDAQAB"
}

// callBackMethod processes the callback method
func (c *CallBack) callBackMethod(requestParams map[string]string) string {
    // Note: Make sure to remove the sign field before formatting the request parameters.
    sign, ok := requestParams["sign"]
    if ok {
        delete(requestParams, "sign")
    }

    // Format the received parameters, calculate the signature, and add the signature value to the request parameters.
    source := toppayutil.ParamFormat(requestParams)

    // Signature verification
    validReq := toppayutil.Verify(c.PLAT_PUBLIC_KEY, source, sign)
    if!validReq {
        // ... Signature verification error
        return "fail"
    }

    // ... Signature verification passed, execute normal business logic

    return "success" // Finally, when the processing is successful, the string "success" must be returned. Otherwise, TopPay will consider the callback to have failed.
}

func main() {
    // Construct the input map
    requestParams := map[string]string{
        "platOrderNum": "S820190712000002",
        "merchantCode": "S820211021094748000001",
        "orderType":    "1",
        "orderNum":     "T1231511321515",
        "orderAmount":  "100.00",
        "realAmount":   "99.91",
        "status":       "30",
        "timestamp":    "1745377181",
        "utr":          "HDFC1234567890",
        "sign":         "Bf8ZfHn7UyHO8TsU8Xkh2sqa0hbpKH1HSPampNXxzBn5PvJoytb8zPkHuQ...",
    }

    // Instantiate CallBack
    cb := &CallBack{
        PLAT_PUBLIC_KEY: "MIGfMA0GCSqGSIb3DQEBAQUACahEnlP3aRj8yCT+WHzR+VvPBTw9S1i7iYWb+MY09CG/HYuHF4+IxshXDJygmndxKf/esuwPybS8mAd//yubHpmZsmBqg1FffT8VH1APa6ZRWASUp4U01ZrbCCp35QA8FuWrJGMJxGx4xk7KUtV2yujxC8noQIDAQAB",
    }

    // Call the method and print the result
    result := cb.callBackMethod(requestParams)
    fmt.Println("Callback processing result:", result)
}

from TopPaySignUtil import TopPaySignUtil


class CallBack:
    # The platform public key comes from the merchant's background
    PLAT_PUBLIC_KEY = "MIGfMA0GCSqGSIb3DQEBAQUACahEnlP3aRj8yCT+WHzR+VvPBTw9S1i7iYWb+MY09CG/HYuHF4+IxshXDJygmndxKf/esuwPybS8mAd//yubHpmZsmBqg1FffT8VH1APa6ZRWASUp4U01ZrbCCp35QA8FuWrJGMJxGx4xk7KUtV2yujxC8noQIDAQAB"

    # Using a dictionary to receive parameters here is just an example. Please modify it according to the actual situation in actual development.
    def callBackMethod(self, requestParams):
        # Note: Make sure to remove the sign field before formatting the request parameters.
        sign = requestParams.pop('sign', None)

        # Format the received parameters, calculate the signature, and add the signature value to the request parameters.
        source = TopPaySignUtil.param_format(requestParams)

        # Signature verification
        validReq = TopPaySignUtil.verify(self.PLAT_PUBLIC_KEY, source, sign)
        if not validReq:
            # ... Signature verification error
            return "fail"

        # ... Signature verification passed, execute normal business logic

        return "success"  # Finally, when the processing is successful, the string "success" must be returned. Otherwise, TopPay will consider the callback to have failed.

if __name__ == "__main__":
    # Construct the input dictionary
    requestParams = {
        "platOrderNum": "S820190712000002",
        "merchantCode": "S820211021094748000001",
        "orderType": "1",
        "orderNum": "T1231511321515",
        "orderAmount": "100.00",
        "realAmount": "99.91",
        "status": "30",
        "timestamp": "1745377181",
        "utr": "HDFC1234567890",
        "sign": "Bf8ZfHn7UyHO8TsU8Xkh2sqa0hbpKH1HSPampNXxzBn5PvJoytb8zPkHuQ..."
    }
    # Instantiate the CallBack class
    cb = CallBack()
    # Call the method and print the result
    result = cb.callBackMethod(requestParams)
    print("Callback processing result:", result)

const { TopPaySignUtil } = require('./TopPaySignUtil');

class CallBack {
    // The platform public key comes from the merchant's background
    static PLAT_PUBLIC_KEY = `
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAybE+QuZsX5aqpfQTFMqq5HdundWTBDnoSJbI7iDGAcjyOCe5vg0pYUycEreThYYtftSsPePnNpq1R97MrGSLLd2BJ9veCHGAhclSStZo/1VQWvC9H5ANv48quQPgaT06fFRztoyrwDL5PElBQtZHQ54p51fDTVYx6xR3bGjphZN+kv6WyUlDTm9SeCqKfmU2PvgiguyHp6ACK7IGXerdbt0kt0C9zWLUxscu7JuBfmk4K2F2ttQ29TVrOArUHYgBs4wd+AKsiIM0rD76JWikfV7APWVDzWGpPNiGjKmD3ghhtj2LqYrKg2dAuBesKyRIFVKZFfuizciJFJq99OGPswIDAQAB
-----END PUBLIC KEY-----
`;

    // Using an object to receive parameters here is just an example. Please modify it according to the actual situation in actual development.
    callBackMethod(requestParams) {
        // Note: Make sure to remove the sign field before formatting the request parameters.
        const sign = requestParams.sign;
        delete requestParams.sign;

        // Format the received parameters, calculate the signature, and add the signature value to the request parameters.
        const source = TopPaySignUtil.paramFormat(requestParams);

        // Signature verification
        const validReq = TopPaySignUtil.verify(CallBack.PLAT_PUBLIC_KEY, source, sign);
        if (!validReq) {
            // ... Signature verification error
            return "fail";
        }

        // ... Signature verification passed, execute normal business logic

        return "success"; // Finally, when the processing is successful, the string "success" must be returned. Otherwise, TopPay will consider the callback to have failed.
    }
}

const newObj = new CallBack();
console.log(newObj.callBackMethod({
     "platOrderNum":"S820190712000002",
    "merchantCode":"S820211021094748000001",
    "orderType":"1",
    "orderNum" : "T1231511321515",
    "orderAmount" : "100.00",
    "realAmount":"99.91",
    "status":"30",
    "timestamp":"1745377181",
    "utr":"HDFC1234567890",
    "sign" :"Bf8ZfHn7UyHO8TsU8Xkh2sqa0hbpKH1HSPampNXxzBn5PvJoytb8zPkHuQ...",
}))

Request Address

• Request method: POST
• Request address: Customizable

Request Parameters

Parameter	Required	Description	Example
platOrderNum	Y	Platform order number	S820190712000002
merchantCode	Y	Merchant ID	S820211021094748000001
orderType	Y	Order type	1:pay 2:loan
orderNum	Y	Merchant order number	T1231511321515
orderAmount	Y	Order amount(Unit: 1 rupees)	100.00 This is the standard amount.
realAmount	N	User's actual payment amount(Unit: 1 rupees)	99.01Used only when needed, and rarely used.
status	Y	Order status	20: Processing 30: Success 40: Failure
timestamp	Y	Timestamp (seconds), Get the system real-time time stamp	1745377181
utr	N	Uniform Transaction Reference	HDFC1234567890
sign	Y	Signature	Bf8ZfHn7UyHO8TsU8Xkh2sqa0hbpKH1HSPampNXxzBn5PvJoytb8zPkHuQ

Request Message Example

{
  "platOrderNum": "S820190712000002",
  "merchantCode": "S820211021094748000001",
  "orderType": "1",
  "orderNum": "T1231511321515",
  "orderAmount": "100.00",
  "realAmount": "99.01",
  "status": "30",
  "timestamp": "1745377181",
  "utr": "HDFC1234567890",
  "sign": "Bf8ZfHn7UyHO8TsU8Xkh2sqa0hbpKH1HSPampNXxzBn5PvJoytb8zPkHuQ"  
}

Response Parameters

If the processing is successful, return the string "success".

Response Message Example

"success"