Subscription Create

Request URL

https://{{gateway_domain}}/pg/v2/payment/subscription/create

Request Parameters

HTTP Method

POST

HTTP Header

Field	Data Type	Length Limit	Required	Description
Content-Type	String	N/A	YES	This field value only supports application/json.
Accept	String	N/A	YES	This field value only supports application/json.
Authorization	String		YES	Authorization: {type} {credentials}, refer to the Signature specification

HTTP Body

Field	Data Type	Length Limit	Required	Description
merchantSubscriptionNo	String	50	YES	Merchant-generated subscription number. Uniqueness is recommended.
description	String	80	YES	Order title. In some scenarios, if the consumer sees the order information, this field content may show.
payer	JSON Object		YES	Payer information. Refer to the payer parameter description below.
billingModel	JSON Object		YES	User subscription model. Refer to Billing Models.
scheduleUnit	String	20	YES	Subscription period unit. Refer to Schedule Unit.
scheduleLength	String	20	YES	Subscription period step length, indicating how many units in one period.
marketingStrategy	JSON Object		YES	Marketing strategy data.
tradeEnv	JSON Object			User trade environment information.
merchantAttach	String	255	NO	If used, this field will be returned as-is in sync/async notifications and order query responses.
notifyUrl	String	255	YES	When the order payment is successful, the platform will notify the merchant by calling this URL.
returnUrl	String	255	YES	If the upstream supports synchronous redirection, the platform will redirect the user's page to this URL.

• billingModel parameter structure description
  • billingModel is dynamic, containing a fixed field type, and different fields depending on type.

Field	Data Type	Length Limit	Required	Description
type	String	20	YES
amount	String	18	YES	Amount per period. Integer part 1-15 digits with 2 decimals, e.g. "100.05".
currency	String	3	YES	ISO currency code of the amount. Refer to the currency list.

• marketingStrategy parameter structure description
  • marketingStrategy is dynamic, containing a fixed field type, and different fields depending on type.

Field	Data Type	Length Limit	Required	Description
type	String	20	YES

• payer parameter notes
  • Choose one of email or phone.

Field	Data Type	Length Limit	Required	Description
userId	String	64	NO	Payer ID
name	String	80	NO	Payer name
email	String	80	NO	Payer email. At least one of email or phone is required.
phone	String	20	NO	Payer phone. At least one of email or phone is required.

• tradeEnv parameter description

Field	Data Type	Length Limit	Required	Description
deviceId	String	50		Payer device ID
ip	String	32		Payer device IP

Response Data

HTTP Header

Field	Data Type	Required	Description
Content-Type	String	YES	This field value only supports application/json.
Authorization	String	YES	Authorization: {type} {credentials}, refer to the Signature specification

HTTP Body

Field	Data Type	Required	Description
code	String	YES
errorMessage	String	NO	Error message
data	JSON Object	NO

Description of data field

Field	Data Type	Required	Description
subscriptionNo	String	YES	Subscription number
merchantSubscriptionNo	String	YES	Merchant subscription number
action	JSON Object	YES	Variant return fields

Description of action field

• payUrl is the payment link generated by the platform. Users click it to be redirected to the platform to pay.

{
    "action": {
        "payUrl": "https://xxx.yy"
    }
}

::::

Examples

Request

curl https://{{gateway_domain}}/pg/v2/payment/subscription/create \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H 'Authorization: V2_SHA256 appId=1111b620f93b48c5904210ff47bb1111,sign=9e494e8a91bcdd08f18ad5b2cfdbfd5654f5c00c89f8216eebd7c1637b6ce01b,timestamp=1714128828114,nonce=C7CA27DC6D55DA935DFC8450C721CC99' \
  -d '{
  "merchantSubscriptionNo": "MSN-1161",
  "description": "subscription test",
  "payer": {
    "userId": "test_id",
    "name": "testName",
    "email": "[email protected]",
    "phone": "00000000"
  },
  "billingModel": {
    "type": "FIXED_SCHEDULE_AND_FIXED_AMOUNT",
    "amount": "10.00",
    "currency": "RUB"
  },
  "scheduleUnit": "MONTH",
  "scheduleLength": "1",
  "marketingStrategy": {
    "type": "DEFAULT"
  },
  "tradeEnv": {
    "ip": "127.0.0.1",
    "deviceId": "02efc74d-3988-4f0d-8cc8-0cb78bded719"
  },
  "merchantAttach": "merchant attach",
  "notifyUrl": "https://example.com/notifyurl",
  "returnUrl": "https://example.com/returnurl"
}'

Response

HTTP/1.1 200 OK
Content-Type: application/json
Server: nginx/1.18.0
Date: Mon, 06 Mar 2024 12:00:00 GMT
Authorization: V2_SHA256 appId=1111b620f93b48c5904210ff47bb1111,sign=ac6ae72f8c46f5c2092c3dab9bb0e08b6cdb6d5e7ff8ad190499a8955d57f297,timestamp=1714128245401,nonce=28FA11BF8FD1309767551B4FD8A57BD5

{
    "code": "OK",
    "errorMessage": null,
    "data": {
        "subscriptionNo": "20240423220624300800001097000004",
        "merchantSubscriptionNo": "MSN-1161",
        "action": {
            "payUrl": "https://xxx.yy"
        }
    }
}

Notes

If subsequent debits fail, there are several scenarios:

• If the user cancels the authorization at the bank side, do not retry and close the subscription directly.
• If the user has not canceled the authorization but has insufficient balance, retry three times, once per day. If unsuccessful after three tries, stop retrying.