Create Payment Token

Introduction

• Merchant created recharge order in own system，and then submit recharge parameters to HitPoints，HitPoints generates payment token and redirect_url and response to merchant.

API Url

​ sandbox：https://api.sandbox.hitpoints.com/v1/reload/create

​ production：https://api.hitpoints.com/v1/reload/create

Request Method

​ POST

Request Parameters

Parameters	Required	Type	Description
reference_id	Yes	string(45)	The unique order Id in merchant's system
body	Optional	string(128)	some description for the order from merchant
detail	Optional	string(1000)	another description for the order from merchant
attach	Optional	string(128)	another description for the order from merchant
currency	Optional	string(3)	merchant define the currency of the recharge order
amount	Optional	number	merchant define the amount of recharge order
return_url	Yes	string(255)	when user completed recharge ,redirect user to the specified return_url
random_key	Yes	string(16)	randomly set the value with random string

Request Success Response

  {
      "data": {
          "token": "z60lRM3cuxC2oFQM4avfo5b6XehNOVdj/gE43Q==",
          "reference_id": "20216882095",
          "currency": "CNY",
          "amount": "10.00",
          "body": "HitPoint点卡定额充值",
          "detail": "充值10元",
          "attach": "HuaXia Game Center",
          "state": "pending",
          "return_url": "http://merchant.store.com/order/detail",
          "pay_method": "web",
          "expire_time": 1568000276,
          "redirect_url":" https://api.hitpoints.gg/v1/reload/pay?token=ejYwbFI4bmN1eEJscmJlN3JJQWN0ekFHR1hHYzRZWm9oS1RyVG5YTjd3PT0
"
      },
      "code": 200,
      "message": "ok",
      "success": true
  }

Response Field Description

Field	Description
code	The response code describe the request is success or not, code = 200 means success
message	The description message to the code
success	Describe the code with bool, when code = 200 , it's true, otherwise it's false

These fields below will response when code=200

Fields	Description
data	the response data
token	payment token
reference_id	Merchant's unique orderID in merchant's system
currency	Order currency
amount	Order recharge amount
body	Order content described by merchant
detail	Order detail described by merchant
attach	Order attached information described by merchant
state	Recharge state：pending=waiting for pin verify, success=pin verified success, cancel= order was canceled, expired=order is expired
return_url	after pin was verified, HitPoints payment pay will redirect user to the return_url
pay_method	the method to call PIN Verify, web or api
expire_time	the token expire time
redirect_url	a payment url with token, merchant redirect user to this url for payment

Response Header：

Fields	Description
Sign	The signature from HitPoints server
Date-GMT	The Time String for HitPoints calculate response signature

Notice: if request failed，that the code!=200, or this is no data field in response body，there will be no Sign field in response header

Fail response example：

{
      "code": 400104,
      "message": "merchant reference_id already exists",
      "success": false
  }

Jump to payment url

After success create payment token，redirect user to the payment redirect_url，user will complete PIN verify and then redirect to return_url.

Payment result

HitPoints provided two ways to get the payment results： 1. when user's PIN was verified，HitPoints will send notification request to merchant's system；2. merchant can query the payment result through query payment result API.

Asynchronous notification

When user completed PIN verification，HitPoints will request merchant's notification url，to notice the order recharge amount with currency and other information. The request method is POST.

{
    "transaction_id": 26,
    "pin_sn": "W000000023Y00001",
    "currency": "CNY",
    "amount": "10.00",
    "pay_time": 1587438324,
    "reference_id": "20200421030349",
    "merchant_id": 10003,
    "body": "Game direct top up",
    "detail": "Game top up with hitpoints currency MYR and amount=10.",
    "attach": "order=12&transaction=1&user_name=bbc",
    "pay_method": "web",
    "result": "success"
}

The data above is an example of notification request

Fields	Type	Description
transaction_id	Int	HitPoints Transaction ID
pin_sn	String	HitPoints PIN Serial Number（Not Pin Secret）
Currency	String	Currency Code
Amount	String	Recharge amount
Pay_time	int	Recharge timestamp
Reference_id	string	The referenceID from merchant
Merchant_id	int	Merchant User ID
body	string	The body parameter from merchant
attach	string	The attach parameter from merchant
pay_method	string	The pay method, web or api
result	string	The payment result：success or fail

Merchant should validate the signature in request headers from HitPoints when got the payment notification。

Notice: when merchant got the callback notification，merchant need to output success as response content. After HitPoints got the success response，HitPoints will stop the payment result callback notification. If HitPoints did not get the success response，HitPoints will repeat the notification over a period, also when merchant handle the notification request, merchant should check if it's a repeated notification to avoid recharging to users repeatedly.

Query payment result

After redirect users to the payment page, the merchant can also actively poll the recharge results through Query Payment Result Api regularly.