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

ParameterRequiredDescription

Content-Type

Recommended

application/json

Authorization

Yes

Basic Base64(app_id:security_key)

Request Parameters (JSON format)

ParameterTypeRequiredMax 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)

ParameterTypeDescription

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

ParameterRequiredDescription

Content-Type

Recommended

application/json

Authorization

Yes

Basic Base64(app_id:security_key)

Request Parameters (JSON format)

ParameterTypeRequiredMax 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)

ParameterTypeDescription

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

Last updated