Skip to main content

Server REST API

Server Development Guide​

Server REST API​

tip

Please refer to the Base URL, Request Format and Response Format descriptions in the Data Storage REST API documentation. Since this set of interfaces is for calling between servers, only the master key authentication method is supported. Do not use or expose the master key on the client side. The master key is the serverSecret of the application in the DC backend.

URLHTTPFunction
/open/payment/v1/orders/<order_id>GETQuery order information
/open/payment/v1/orders/<order_id>/verifyPOSTVerify order
/open/payment/v1/orders/<order_id>/refundPOSTOrder refund

Query Order​

You can query the detailed information of an order by order ID and determine the current payment status.

curl -X POST \
  -H 'X-LC-Id: {{appid}}' \
  -H 'X-LC-Key: {{masterKey}},master' \
  https://{{host}}/open/payment/v1/orders/1670731970469806082

The return value is a JSON object of an order. 

{
   "data" : {
      "amount" : 299,
      "client_id" : "UeTShOwxDrAsf232WN",
      "currency" : "USD",
      "extra" : "648ff2d31a81c",
      "goods_open_id" : "game-11190",
      "minor_unit" : 2,
      "order_id" : "1670680390026510338",
      "order_token" : "2cf31318c6f4939d5eaf2e9431bf45f2",
      "region_id" : "HK",
      "status" : "refund.succeeded",
      "user_id" : 3173821787,
      "verified" : false
   },
   "success" : true
}

Verify Order​

After the payment is successful, verifying the order indicates that the payment result has been confirmed and the delivery will be completed for the buyer. The order status will change from charge.succeeded to charge.confirmed.

curl -X POST \
  -H 'X-LC-Id: {{appid}}' \
  -H 'X-LC-Key: {{masterKey}},master' \
  https://{{host}}/open/payment/v1/orders/1670731970469806082/verify?token=2cf31318c6f4939d5eaf2e9431bf45f2

The return value is a JSON object of an order. 

{
   "data" : {
      "amount" : 299,
      "client_id" : "UeTShOwxDrAsf232WN",
      "currency" : "USD",
      "extra" : "648ff2d31a81c",
      "goods_open_id" : "game-11190",
      "minor_unit" : 2,
      "order_id" : "1670680390026510338",
      "order_token" : "2cf31318c6f4939d5eaf2e9431bf45f2",
      "region_id" : "HK",
      "status" : "refund.succeeded",
      "user_id" : 3173821787,
      "verified" : false
   },
   "success" : true
}

The only scenarios where the game server should use the REST API are when querying and validating orders. An example of an exception response is shown below:

// 1004 - Order does not exist    1018 - Order verification error
{
   "data" : {
      "code" : 1004,
      "error" : "order_not_found",
      "error_description" : "Order does not exist",
      "msg" : "Order does not exist"
   },
   "success" : false
}

Order Refund​

Refund an order. 

curl -X GET \
  -H 'X-LC-Id: {{appid}}' \
  -H 'X-LC-Key: {{masterKey}},master' \
  https://{{host}}/open/payment/v1/orders/1670731970469806082/refund

Order Object Fields​

FieldMeaning
client_idClient ID
user_idUser OpenID
order_idOrder ID
order_tokenToken used for verification
goods_open_idItem ID
amountOrder Amount
currencyCurrency
monior_unitCurrency Precision
region_idBuyer Region
statusOrder Status
verifiedWhether verified before
extraBusiness Additional Data

Order Status​

StatusMeaning
charge.pendingPending Payment
charge.succeededPayment Successful
charge.confirmedVerified
charge.overduePayment Closed Due to Timeout
refund.pendingRefunding
refund.succeededRefund Successful
refund.failedRefund Failed
refund.rejectedRefund Rejected

Role Information​

The game needs to go to TapTap Developer Centre > Your Games > Game Services > TapTap payments > Items and Orders > Website Sele Settings > Game Info API provide valid API to query user and server info in game. (Required)

Routing address

Games can be customised

Request method

POST-application/json

In

ParametersTypologyConnotationNecessary or not
open_idstringuser-unique IDY
languagestringLanguage for displaying labelY

Out

Example 1: Suitable for identifying a top-up object through a "role".
{
    "data": {
        "depth_title": [
            {
                "label": "role",
                "value": "role"
            }
        ],
        "player": [
            {
                "label": "adventurer A",
                "value": "a"
            },
            {
                "label": "adventurer B",
                "value": "b"
            }
        ]
    },
    "success": true
}
Example 2: Suitable for identifying a top-up object by "server" and "role".
{
    "data": {
        "depth_title": [
            {
                "label": "server",
                "value": "server"
            },
            {
                "label": "role",
                "value": "role"
            }
        ],
        "player": [
            {
                "label": "server S1",
                "value": "S1",
                "children": [
                    {
                        "label": "adventurer A",
                        "value": "a"
                    },
                    {
                        "label": "adventurer B",
                        "value": "b"
                    }
                ]
            },
            {
                "label": "server S2",
                "value": "S2",
                "children": [
                    {
                        "label": "adventurer C",
                        "value": "c"
                    }
                ]
            }
        ]
    },
    "success": true
}
Example 3: It is suitable to determine a top-up object by "region", "server", "role".
{
    "data": {
        "depth_title": [
            {
                "label": "region",
                "value": "region"
            },
            {
                "label": "server",
                "value": "server"
            },
            {
                "label": "role",
                "value": "role"
            }
        ],
        "player": [
            {
                "label": "America East",
                "value": "ae",
                "children": [
                    {
                        "label": "server S1",
                        "value": "S1",
                        "children": [
                            {
                                "label": "adventurer A",
                                "value": "a"                            
                            }
                        ]
                    },
                    {
                        "label": "server S2",
                        "value": "S2",
                        "children": [
                            {
                                "label": "adventurer C",
                                "value": "c"
                            }
                        ]
                    }
                ]
            }
        ]
    },
    "success": true
}

Purchase Configuration API​

The game needs to go to TapTap Developer Centre > Your Games > Game Services > TapTap payments > Items and Orders > Website Sele Settings > Purchase Limit API provide valid API to query user and server info in game. (Optional)

Routing address

Games can be customised

Request method

POST-application/json

In

Example 1

ParametersTypologyConnotationNecessary or not
rolestringrole IDY

Example 2

ParametersTypologyConnotationNecessary or not
serverstringserver IDY
rolestringrole IDY

Example 3

ParametersTypologyConnotationNecessary or not
regionstringregion IDY
serverstringserver IDY
rolestringrole IDY

Out

ParametersTypologyConnotationNecessary or not
typestringRule type：blacklist - Commodity blacklist，whitelist - Commodity whitelistY
liststringCommodity Unique IDY
{
    "data": {
        "type": "blacklist",
        "list": [
            "com.gooplin.il.GiftPackOrcTask",
            "com.gooplin.il.ActivityPack006"
        ]
    },
    "success": true
}

TapPay-Signature header rule​

Please refer to Webhook Signature Verification for the signing rules of the Role Query and Purchase Configuration API interfaces, which are the same.

Webhook Callback​

Webhook Description​

Currently, Webhook only monitors the "Refund Successful", "Refund Failed", "charge Successful" event. For successful payment, it is recommended to take the initiative to verify the order and complete the delivery according to the order status.

The game needs to go to TapTap Developer Centre > Your Games > Game Services > TapTap payments > Items and Orders > Webhooks Settings provide valid API to query user and server info in game. (Required)

Webhook Verification​

Webhook is an HTTP POST request that passes signature information through the TapPay-Signature header. The format is timestamp, signature such as: 

 TapPay-Signature: 1687224754,4dd293a514223c052513c1db449106f13710c733855d2af6654948675e1624e7

According to the above header, ts = 1687224754 is obtained. You can first confirm whether its difference from the current system time is too large to ensure that it is not a reused request.

The request body is a JSON string defined as payload.

{
    "order":{
        "id":1721791738662895617,
        "client_id":"3l5b2phi8k2snze3hs",
        "user_id":3173820362,
        "open_id":"I1LEuujBQMqM4d9CWpVQug==",
        "user_region":"CL",
        "merchant_order_id":"f84f6778-9357-413c-b503-066900667ff5",
        "payment_provider":"STRIPE",
        "payment_channel":"CARD",
        "goods_id":"com.gooplin.il.goods1030",
        "goods_name":"test20230920-name",
        "status":"charge.confirmed",
        "amount":"990",
        "tax":"0",
        "fee":"0",
        "currency":"CLP",
        "create_time":1699342114,
        "pay_time":1699342118,
        "extra":"{\"server\":\"S1\",\"role\":\"b\"}",
        "order_refund":{
            "id":1721791738662833333,//refund number
            "reason":"Props have not arrived",//Reason for refund
            "status":"done", //status：pending，refunding，done，overrule，failed
            "comments":"",//Requests for refunds, comments on reviews by game developers
            "comments_picture":"",//Attachment to the audit opinion
            "errs":"",// Refund Exception Information
            "created_at":1700449577
            "updatedAt":1700449577
        }
    },
    "event_type":"refund.succeeded"
}

You also need the API key configured in the DC backend as the secret of the HmacSHA256 algorithm to finally get

sign = HmacSHA256(secret, ts + "." + payload )

Compare whether the calculated sign is the same as the signature part of TapPay-Signature

Webhook Content​

The Webhook content contains event_type and order information. The currently supported event_type are:

event_typeConnotation
refund.succeddedRefund Successful
refund.failedRefund Failure
charge.succeededCharge Successful

Currently, Webhook supports listening to "recharge success", "refund success" and "refund failure" events with the same format of in-parameters and out-parameters.

ParametersTypologyConnotationNecessary or not
idlongOrder Unique IDY
client_idstringClient IDY
user_idlongUser TapIDY
open_idlongUser Open IDY
user_regionstringUser regionY
merchant_order_idstringMerchant orders unique IDY
payment_providerstringPayment MethodsY
payment_channelstringPayment ChannelsY
goods_idstringCommodity Unique IDY
goods_namestringProduct NameY
statusstringOrder StatusY
amountstringMonetary ValueY
taxstringTaxesY
feestringFeeY
currencystringCurrencyY
create_timelongCreate TimeY
pay_timelongPay timeY
extrastringCustomised information, e.g. server, role informationY
order_refundobjectRefund information, default nullY
Example of a successful recharge event
{
    "order":{
        "id":1721791738662895617,
        "client_id":"3l5b2phi8k2snze3hs",
        "user_id":3173820362,
        "open_id":"I1LEuujBQMqM4d9CWpVQug==",
        "user_region":"CL",
        "merchant_order_id":"f84f6778-9357-413c-b503-066900667ff5",
        "payment_provider":"STRIPE",
        "payment_channel":"CARD",
        "goods_id":"com.gooplin.il.goods1030",
        "goods_name":"test20230920-name",
        "status":"charge.confirmed",
        "amount":"990",
        "tax":"0",
        "fee":"0",
        "currency":"CLP",
        "create_time":1699342114,
        "pay_time":1699342118,
        "extra":"{\"server\":\"S1\",\"role\":\"b\"}",
        "order_refund":{}
    },
    "event_type":"charge.succeeded"
}
Example of a successful refund event
{
    "order":{
        "id":1721791738662895617,
        "client_id":"3l5b2phi8k2snze3hs",
        "user_id":3173820362,
        "open_id":"I1LEuujBQMqM4d9CWpVQug==",
        "user_region":"CL",
        "merchant_order_id":"f84f6778-9357-413c-b503-066900667ff5",
        "payment_provider":"STRIPE",
        "payment_channel":"CARD",
        "goods_id":"com.gooplin.il.goods1030",
        "goods_name":"test20230920-name",
        "status":"charge.confirmed",
        "amount":"990",
        "tax":"0",
        "fee":"0",
        "currency":"CLP",
        "create_time":1699342114,
        "pay_time":1699342118,
        "extra":"{\"server\":\"S1\",\"role\":\"b\"}",
        "order_refund":{
            "id":1721791738662833333,//refund number
            "reason":"Props have not arrived",//Reason for refund
            "status":"done", //status：pending，refunding，done，overrule，failed
            "comments":"",//Requests for refunds, comments on reviews by game developers
            "comments_picture":"",//Attachment to the audit opinion
            "errs":"",// Refund Exception Information
            "created_at":1700449577
            "updatedAt":1700449577
        }
    },
    "event_type":"refund.succeeded"
}

Out

Success will return the string: success, failure will return any other string.

Routing address

Games can be customised

Request method

POST-application/json