Recurring Payment

Recurring Payment

Request Base URL

  Test Environment : https://gateway-test.pagsmile.com
  Prod Environment : https://gateway.pagsmile.com

EndPoints

  /trade/recurring

Request Header

Parameter	Required	Description
Content-Type	Recommended	application/json
Authorization	Yes	Basic Base64(app_id:security_key)

Request Parameters (JSON format)

Parameter	Type	Description	Max Length(or Default Value)
app_id*	string	App's ID is in dashboard	32
out_trade_no*	string	Given by the Merchant (Is in their system)	64
method*	string	CreditCard or Wallet	32
order_currency*	string	Check here for supported currency	3
order_amount*	decimal	Request payment amount	0.01 ~ 99999999999999.99
subject*	string	Payment reason or item title	128
content*	string	Payment reason detail or item detail	255
trade_type*	string	Response content type, WEB will return a checkout URL	WEB
timeout_express*	string	m(minutes), h(hours), d(days), c(current day)	90m
format*	string	Only JSON supported	JSON
timestamp*	string	yyyy-MM-dd HH:mm:ss	19
version*	string	Fix to 2.0	2.0
notify_url*	string	IPN URL to merchant (start with http)
return_url*	string	Web page return URL to merchant (start with http)
buyer_id*	string	Merchant user's ID
interval*	string	D(day), W(week), M(month), Y(year)	1M
quantity*	number	Quantity of recurring	0
trial_period*	string	Trial period
trial_amount*	decimal	Trial amount (when trial_amount is not blank)	> 0

Request Sample

curl --location --request POST 'https://gateway.pagsmile.com/trade/recurring' \
--header 'Authorization: Basic Base64(appid:security_key)' \
--header 'Content-Type: application/json' \
--data-raw '{
    * "app_id": "1639****096",
    * "timestamp": "2024-05-20 13:42:06",
    * "version": "2.0",
    * "method": "Wallet",
    * "order_amount": "16.66",
    * "order_currency": "CNY",
    * "trial_amount":"6.66",
    * "trial_period":"5m",
    * "interval":"30m",
    * "quantity":3,
    * "out_trade_no": "out_29****00",
    * "subject": "trade pay test",
    * "content": "trade pay test conent",
    * "trade_type": "WEB",
    * "notify_url": "http://demo.gemini-tiger.cn/callback/success",
    * "return_url": "https://pagsmile.com/zh/",
    * "buyer_id": "299****600",
    * "timeout_express":"10900m"
}'

Http Response (JSON format)

Parameter	Type	Description
code	string	Return code
msg	string	Return msg
sub_code	string	Return sub code (only error)
sub_msg	string	Return sub msg (only error)
out_trade_no	string	Request out_trade_no
trade_no	string	Pagsmile trade NO.
web_url	string	Checkout URL

Return Code (Success)

{
    "code": "10000",
    "msg": "Success",
    "out_trade_no": "{out_trade_no}",
    "trade_no": "{trade_no}",
    "web_url": "http://checkout.pagsmile.com?prepay_id={$prepay_id}",
    "prepay_id": "{$prepay_id}"
}

Return Code (Fail)

{
    "code": "40002",
    "msg": "Business Failed",
    "sub_code": "invalid-signature",
    "sub_msg": "invalid signature"
}

IPN Notifications

Follow the general IPN notifications guide to receive our IPN notification messages, meantime with recurring sub orders, we will also send the parameter period to specific current period of the order.

Content-Type: application/json
Method: POST
Header: Pagsmile-Signature
Body:
  {
  	"amount":"",
  	"out_trade_no":"",
  	"method":"",
  	"trade_status":"",
  	"trade_no":"",
  	"currency":"",
  	"out_request_no":"",
  	"app_id":"",
    "timestamp":"",
    "user":{
      "identify":{
        "number":"",
        "type":""
      },
      "phone":"",
      "email":""
    },
    "card":{
      "card_no":"F6L4"
    },
    "period": 1
  }

Attention!!!

return_url is not in the request parameters, if needed, just append the return_url after the web_url when redirect:

http://checkout.pagsmile.com?prepay_id={$prepay_id}

Cancel Recurring Payment

Request Base URL

  Test Environment : https://gateway-test.pagsmile.com
  Prod Environment : https://gateway.pagsmile.com

EndPoints

  /trade/recurring/cancel

Request Header

Parameter	Required	Description
Content-Type	Recommended	application/json
Authorization	Yes	Basic Base64(app_id:security_key)

Request Parameters (JSON format)

Parameter	Type	Description	Max Length(or Default Value)
app_id*	string	App's ID is in dashboard	32
timestamp*	string	yyyy-mm-dd HH:mm:ss	19
version*	string	fix to 2.0	2.0
out_trade_no*	string	Given by the Merchant (Is in their system)	64

Request Sample

curl --location --request POST 'https://gateway.pagsmile.com/trade/recurring/cancel' \
--header 'Authorization: Basic Base64(appid:security_key)' \
--header 'Content-Type: application/json' \
--data-raw '{
    * "app_id": "app_id",
    * "timestamp": "{{datetime}}",
    * "version": "2.0",
    * "out_trade_no": "{{$randomUUID}}"
}'

Http Response (JSON format)

Parameter	Type	Description
code	string	Return code
msg	string	Return msg
sub_code	string	Return sub code(only error)
sub_msg	string	Return sub msg(only error)
out_trade_no	string	Request out_trade_no
recurring_status	string	Recurring status

Return Code (Success)

{
    "code": "10000",
    "msg": "Success",
    "out_trade_no": "{out_trade_no}",
    "recurring_status": "CANCEL"
}

Return Code (Fail)

{
    "code": "40002",
    "msg": "Business Failed",
    "sub_code": "invalid-signature",
    "sub_msg": "invalid signature"
}