API Mobile Topup

API Mobile Topup

Chat with AI▼

Endpoint: /api/v2/service/topup/charging

Method: POST

Header: How to generate JWT_TOKEN

Language: en | vi

{
    "X-APPOTAPAY-AUTH": Bearer JWT_TOKEN,
    "Content-Type": "application/json",
    "Language": LANGUAGE
}

Params

Params	Required	Type	Description	Note
partnerRefId	√	String	This is unique code corresponding to a request send	max_length: 50
telco		String	Vendor name (see more Table of content list vendor)
telcoServiceType	√	String	Service type prepaid: Topup mobile prepaid postpaid: Topup mobile postpaid
productCode	√	String	Product code (see more API to get list product code)
phoneNumber	√	String	Phone number charge topup (format: 09x, 08x,..)
signature	√	String	Signature of parameter passed to the API, the parameter is included into signature like this: partnerRefId + phoneNumber + productCode + telco + telcoServiceType (see more how to generate signature)

Note:

- APPOTAPAY has supported Partners in proactively checking the network of the transmitted phone number.

- Partners can use the common product code table to transmit to the API without having to clearly define the product_code according to each network of the phone number (This code table is used for regular topup, not for data topup).

Data result

Params	Type	Description
errorCode	Integer	Error code result
message	String	Description error code detail
transaction	Object	Transaction object
transaction.phoneNumber	String	Phone number to charge topup
transaction.amount	Integer	Amount transaction
transaction.productCode	String	Product code
transaction.topupAmount	Integer	Amount topup
transaction.appotapayTransId	String	Transaction id from AppotaPay
transaction.time	String	Transaction time (in RFC-3339 standard format)
transaction.telco	String	Vendor name Telco may be different from the input request due to actual data recorded from provider
transaction.telcoServiceType	String	Service type (This value may vary based on the actual information returned by the telecom provider.)
account	Object	Account information
account.balance	Integer	Balance account after topup
signature	String	Signature of parameter passed to the API, the parameter is included into signature like this:(amount + appotapayTransId + errorCode + phoneNumber + productCode + time + topupAmount) (see more how to generate signature)

Example

Request

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

Response

Success

{
    "errorCode": 0,
    "message": "Success",
    "transaction": {
        "phoneNumber": "0866123456",
        "amount": 10000,
        "productCode": "viettel_10",
        "topupAmount": 10000,
        "appotapayTransId": "01J7G2DYZTPCGHM3AAF8ANZC7J",
        "time": "2024-09-13T17:48:06+07:00",
        "telco": "viettel",
        "telcoServiceType": "prepaid",
    },
    "account": {
        "balance": "121000000"
    },
    "signature": "e5f61a7eca55ca1c5a1b6305acfa0e52f6d3d562de1b9780faf5f247ed10ab8d"
}

Error

{
    "errorCode": 40,
    "message": "The system is under maintenance, please try again later"
}

Code Examples

curl --location 'https://gateway.dev.appotapay.com/api/v2/service/topup/charging' \
  --header 'X-APPOTAPAY-AUTH: JWT_TOKEN' \
  --header 'Content-Type: application/json' \
  -d '{
  "partnerRefId": "AB123",
  "telco": "viettel",
  "telcoServiceType": "prepaid",
  "phoneNumber": "0866123456",
  "productCode": "viettel_10",
  "signature": "5a2774918a29cf4d2bdb78cccceb956f4c27837fad09a03a56e1df68b1bf29dd"
}'

Request

REQUEST

Base URL

https://gateway.dev.appotapay.com

Development server

Path

Auth REQUIRED

Bearer Token

Body REQUIRED

Example (from schema)

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