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

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	Required	Max Length(or Default Value)	Description
app_id	string	yes	32	App's ID is in dashboard
timestamp	string	yes	19	yyyy-mm-dd HH:mm:ss
version	string	yes	2.0	fix to 2.0
out_trade_no	string	yes	64	Given by the Merchant (Is in their system)

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"
}