API Payment Subscription

Request URL: POST /api/subscription

1. After the user makes a payment, they will be redirected to the page specified by the callbackUrl. If the payment fails, it indicates the end of this payment process. If the payment is successful, it means the user's subscription has been completed.

2. Whether the subscription is successful or not, an asynchronous notification will be sent to the interface address specified by the notificationUrl.

Request Parameters

Parameter	Type	Required	Description
transactionId	String(128)	Required	Merchant unique transaction ID, generally used to prevent repeated submission of one order
orderId	String(128)	Required	Merchant order ID, can be requested repeatedly but only one successful transaction exists
currency	String(3)	Required	Currency (Example: CNY/USD)
amount	Number(12,3)	Required	Transaction amount
transactionIp	String(128)	Required	Cardholder transaction IP
appId	Number(20)	Required	System -> Website App -> APP
callbackUrl	String(255)	Required	3D/Checkout callback URL (Generally used for page display logic, such as redirecting to the original product page)
notificationUrl	String(255)	Required	Asynchronous notification URL, if this parameter is not empty, a notification will be sent to this address after the transaction is completed (usually used to process order status)
productInfos	Array	Required	Product information (ProductInfo Details)
card	Object	Required	Card information (Card Details)
extension	Object	Required	Important Subscription Parameter, please refer to Subscription Details
billingAddress	Object	Required	Note: Country field is required Billing information (BillingAddress Details)
shippingAddress	Object	Optional	Shipping information (ShippingAddress Details)
secure	Boolean	Optional	Whether to request 3D transaction, true for 3D transaction,This parameter does not relate to Google Pay™.
browser	Object	Optional	Required for 3D transaction, Request browser parameters (Browser Details)

Request Example

{
  "transactionId": "123456",
  "currency": "USD",
  "amount": "8.88",
  "appId": "123456",
  "callbackUrl": "https://domain/callback",
  "notificationUrl": "https://domain/notification",
  "transactionIp": "127.0.0.1",
  "productInfos": [
    {
      "productName": "Stonebriar Unscented Tea Light Candles with 6-7 Hour Burn Time - White, Pack of 100",
      "currency": "USD",
      "price": "8.88",
      "sku": "123-456-789",
      "quantity": 1,
      "productLink": "https://domain/123-456-789"
    }
  ],
  "card": {
    "expiredYear": "23",
    "expiredMonth": "12",
    "cardNumber": "4200000000000000",
    "cardholder": "san zhang",
    "cvv": "123"
  },
  "billingAddress": {
    "firstName": "Gross",
    "lastName": "Schmidt",
    "country": "CA",
    "email": "[email protected]",
    "city": "Longueuil",
    "address": "3226 rue Saint-Charles",
    "phone": "450-928-5752",
    "state": "Quebec",
    "zipCode": "J4H 1M3"
  },
  "shippingAddress": {
    "firstName": "Gross",
    "lastName": "Schmidt",
    "country": "CA",
    "email": "[email protected]",
    "city": "Longueuil",
    "address": "3226 rue Saint-Charles",
    "phone": "450-928-5752",
    "state": "Quebec",
    "zipCode": "J4H 1M3"
  },
  "browser": {
    "userAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.24 Safari/537.36 Edg/83.0.478.18",
    "referer": "https://www.domain.com"
  },
  "extension": {
    "subscriptionCycle": "WEEK",
    "subscriptionPeriod": 3,
    "subscriptionDescription": "Subscription Description"
  }
}

Return to the instance

Parameter details

The request is successful

{
  "code": 100,
  "isTest": true,
  "appId": 123456,
  "uniqueId": "1669548151356891137",
  "billDescription": "*Description",
  "message": "successful transaction",
  "timestamp": 1686886273516,
  "transactionAmount": "8.88",
  "transactionAt": "2023-06-16 11:31:12",
  "transactionCardNumber": "420000******0000",
  "transactionCurrency": "USD",
  "transactionId": "123456",
  "transactionMessage": "Approved"
}

After the request is successful, use the redirectUrl to jump to 3D

{
  "code": 301,
  "isTest": true,
  "appId": 123456,
  "uniqueId": "1669548151356891137",
  "billDescription": "*Description",
  "message": "order processing",
  "timestamp": 1686886273516,
  "transactionAmount": "8.88",
  "transactionAt": "2023-06-16 11:31:12",
  "transactionCardNumber": "420000******0000",
  "transactionCurrency": "USD",
  "transactionId": "123456",
  "transactionMessage": "Redirect",
  "redirectUrl": "https://domain/redirect/a6354c630cba488caa56a0113bb0ef34"
}

User request for subscription successfully received email template

User's subsequent subscription fee deduction email template

The request failed

{
  "code": 101,
  "isTest": true,
  "appId": 123456,
  "uniqueId": "1669548151356891137",
  "billDescription": "*Description",
  "message": "transaction failed",
  "timestamp": 1686886273516,
  "transactionAmount": "8.88",
  "transactionAt": "2023-06-16 11:31:12",
  "transactionCardNumber": "420000******0000",
  "transactionCurrency": "USD",
  "transactionId": "123456",
  "transactionMessage": "Do not honor"
}