Skip to main content
Version: Lastest

Security

Security

Chat with AI▼

1. How to generate signature for API Mobile Topup​

Applies to both the synchronous topup API (/api/v2/service/topup/charging) and the asynchronous topup API (/api/v2/service/topup/charging-async). The two APIs share the same params and the same way of signing the request.

Example of parameters passed to the API​

{
  "partnerRefId": "AB123",
  "telco": "viettel",
  "telcoServiceType": "prepaid",
  "phoneNumber": "0866123456",
  "productCode": "viettel_10",
  "signature": "5a2774918a29cf4d2bdb78cccceb956f4c27837fad09a03a56e1df68b1bf29dd"
}

The order of parameters to create the signature will be sorted alphabetically.
The parameters are included into signature: partnerRefId + phoneNumber + productCode + telco + telcoServiceType
The string generated with the above parameters will be:

"partnerRefId=AB123&phoneNumber=0866123456&productCode=viettel_10&telco=viettel&telcoServiceType=prepaid"

signature = HMAC_SHA256("partnerRefId=AB123&phoneNumber=0866123456&productCode=viettel_10&telco=viettel&telcoServiceType=prepaid", YOUR_SECRET_KEY)

Example response of the API​

{
  "errorCode": 0,
  "message": "Thành công",
  "transaction": {
    "phoneNumber": "0866123456",
    "amount": 100000,
    "topupAmount": 100000,
    "productCode": "viettel_10",
    "appotapayTransId": "01JCM8K321W0ZFHK99T8JBXR2P",
    "time": "14-11-2024 09:38:43"
  },
  "account": {
    "balance": 3402291841
  },
  "signature": "c0bd34c43314165b1474c190c71fee22bca6bd0cf8273853bb9acb510d6063bf"
}

The order of parameters to create the signature will be sorted alphabetically.
The parameters are included into signature: amount + appotapayTransId + topupAmount + errorCode + time + phoneNumber + productCode
The string generated with the above parameters will be:

"amount=100000&appotapayTransId=01JCM8K321W0ZFHK99T8JBXR2P&errorCode=0&phoneNumber=0866123456&productCode=viettel_10&time=14-11-2024 09:38:43&topupAmount=100000"

signature = HMAC_SHA256("amount=100000&appotapayTransId=01JCM8K321W0ZFHK99T8JBXR2P&errorCode=0&phoneNumber=0866123456&productCode=viettel_10&time=14-11-2024 09:38:43&topupAmount=100000", YOUR_SECRET_KEY)

2. How to generate signature for API Check transaction status​

Example response of the API​

{
  "errorCode": 0,
  "message": "Thành công",
  "transaction": {
    "phoneNumber": "0866123456",
    "amount": 100000,
    "topupAmount": 100000,
    "appotapayTransId": "01JCM8K321W0ZFHK99T8JBXR2P",
    "time": "14-11-2024 09:38:43"
  },
  "signature": "c0bd34c43314165b1474c190c71fee22bca6bd0cf8273853bb9acb510d6063bf"
}

The order of parameters to create the signature will be sorted alphabetically.
The parameters are included into signature: amount + appotapayTransId + topupAmount + errorCode + time + phoneNumber
The string generated with the above parameters will be:

"amount=100000&appotapayTransId=01JCM8K321W0ZFHK99T8JBXR2P&errorCode=0&phoneNumber=0866123456&time=14-11-2024 09:38:43&topupAmount=100000"

signature = HMAC_SHA256("amount=100000&appotapayTransId=01JCM8K321W0ZFHK99T8JBXR2P&errorCode=0&phoneNumber=0866123456&time=14-11-2024 09:38:43&topupAmount=100000", YOUR_SECRET_KEY)

3. How to verify the signature of the asynchronous topup IPN​

Applies to the IPN of the asynchronous topup flow. The partner regenerates the signature from the received data and compares it with the signature sent by AppotaPay, and only updates the order when the two values match.

Example of parameters sent by AppotaPay​

{
  "errorCode": 0,
  "status": "success",
  "appotapayTransId": "01J7G2DYZTPCGHM3AAF8ANZC7J",
  "partnerRefId": "AB123",
  "phoneNumber": "0866123456",
  "productCode": "viettel_10",
  "amount": 10000,
  "topupAmount": 10000,
  "telco": "viettel",
  "telcoServiceType": "prepaid",
  "time": "2026-08-17T10:15:30+07:00",
  "signature": "44b2e44eaaecfbbe5d9512c323affad5a9515a7f606afc486de80b7c2f771f2f"
}

The order of parameters to create the signature will be sorted alphabetically.
The parameters are included into signature: amount + appotapayTransId + errorCode + partnerRefId + phoneNumber + productCode + status + telco + telcoServiceType + time + topupAmount
The string generated with the above parameters will be:

"amount=10000&appotapayTransId=01J7G2DYZTPCGHM3AAF8ANZC7J&errorCode=0&partnerRefId=AB123&phoneNumber=0866123456&productCode=viettel_10&status=success&telco=viettel&telcoServiceType=prepaid&time=2026-08-17T10:15:30+07:00&topupAmount=10000"

signature = HMAC_SHA256("amount=10000&appotapayTransId=01J7G2DYZTPCGHM3AAF8ANZC7J&errorCode=0&partnerRefId=AB123&phoneNumber=0866123456&productCode=viettel_10&status=success&telco=viettel&telcoServiceType=prepaid&time=2026-08-17T10:15:30+07:00&topupAmount=10000", YOUR_SECRET_KEY)