Explanation

1.Interface description

• The white label self-developed service sets the webhook address through the white label backend. When subsequent specified events occur, data will be pushed to this interface
• After the data push fails, it will be pushed again every 3 seconds, and after 5 failed push attempts, it will no longer be pushed.
• The set webhook address must be provided to UPay for verification before it can be successfully pushed.

2.Request method

Request Method	POST
Request Body	Using content type=application/json; Charset=UTF-8 format transmission

3.Header parameter

Parameter	Type	Required	Describe
X-UPA-REQUESTID	String	true	Global unique request ID, kept unique for easy problem localization in the future
X-UPA-TIMESTAMP	Long	true	13 digit timestamp, request initiation time
X-UPA-SIGN	String	true	Signature value

4.Request body parameters

• Request body description
  The request body content is encrypted using the public key set in the white label backend.
• Card webhook events and data format
  Reference Card
• Wallet webhook events and data format
  Reference Wallet

5. Signature

1. Separate event + timestamp + body with | and form a string.
   Example：CC_CONSUME|1755248905430|xxxxxx
2. Use SecretKey to perform Hmac.SHA256 signature on the concatenated string.
   Note: SecretKey can be obtained through the white label system.
3. Base64 the signed data

Parameter	Type	Required	Example value	Describe
event	String	True	CC_CONSUME	Decrypted body data acquisition
timestamp	Long	True	1755248905430	X-UPA-TIMESTAMP in the header parameter
body	String	True	xxxxxx	Webhook

Java

dataimport javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.io.IOException;
import java.util.Base64;
import java.util.Objects;

public class HMACSHA256Signer{
	private String generateHmacSha256(String data , String secretKey) throws Exception {
    Mac mac = Mac.getInstance("HmacSHA256");
    byte[] keyBytes = secretKey.getBytes();
    SecretKeySpec signingKey = new SecretKeySpec(keyBytes , "HmacSHA256");
    mac.init(signingKey);
    byte[] rawHmac = mac.doFinal(data.getBytes());
    return Base64.getEncoder().encodeToString(rawHmac);
	}
}

6.Response

The white label self-developed service receives a request and needs to respond within 5 seconds

• Success: The HTTP status code is equal to 200 and the response content is' SUCCESS'
• Failure: If timeout, HTTP status code is not equal to 200, or the return result is not 'SUCCESS', it will be judged as a failure by UPay

If the response result is judged as a failure, it will resend every 3 seconds, with a maximum of 5 resend attempts. White label self-developed services require appropriate idempotent processing to prevent business exceptions.