Request Body Parameters

application/json

Common Request Parameters

bizContent

• threeDSRequestDataStringConditional
• paymentMethodObjectRequired
• customerObjectConditional
• goodsArrayRequired
• shippingAddressObjectConditional
• billingAddressObjectConditional
• browserInfoObjectConditional
• deviceObjectRequired
• recurringInfoObjectConditional
• merchantRiskIndicatorObjectOptional
• captureDelayHoursintRequired

  • 0 indicates immediate capture
  • -1 indicates manual capture, after successfully calling the unified order API, you still need to call Pre-Authorization Capture, local payment does not support this
• timeExpireString(10)Optional

  Order closure time. 3 minutes to 10 days (if less than 3 minutes, it defaults to 3 minutes; if more than 10 days, it defaults to 10 days). Timestamp format, unit: seconds, example value: 1683530496
• amountString(12)Required

  Transaction amount, the precision is related to the currency, please refer to the appendix Transaction Currencies
• currencyString(3)Required

  Transaction currency, ISO 4217 three-letter code, for specific supported currencies see appendix Transaction Currencies
• merchantTransactionIdString(64)Required

  Merchant website order serial number, a unique identifier for the order, can be used for subsequent order inquiries and reconciliation
• payResultUrlString(255)Conditional

  Custom redirect URL set by the merchant; for 3DS verification, bank online transfer, or virtual wallet payments, it finally needs to redirect to the specified page address by the merchant
• merchantRequestBillDescriptorString(22)Optional

  Merchant-defined dynamic billing descriptor, up to 22 characters. Only English letters, digits, whitespace, and these ASCII punctuation marks are allowed: , . ( ) - / :. Chinese characters and other special characters are not allowed. Different channels may apply appropriate truncation.
• bizTypeString(12)Conditional

  `CardOnFile` transaction mode identifier. Pass the fixed value `CardOnFile` when the first bind-and-pay transaction needs to be processed as `CardOnFile`; if this value was passed when the token was first created, it must also be passed in subsequent repeat purchases using that token. Do not pass this parameter for regular saved-card transactions or when only verifying card details (please contact technical support to use this value)
• merchantUserIdString(256)Conditional

  Required for CardOnFile or CodeGrant mode
• CardOnFile: Cardholder ID on the merchant's website, globally unique, used to identify the cardholder and associate stored card information
• CodeGrant: Member ID, user's member ID on the merchant's website

createTokenString(1)Conditional

Y/N, whether to create a token. This field controls whether a reusable payment credential is generated after the current payment succeeds. In Non-Hosted mode, pass `Y` when the first saved-card payment needs to generate a payment credential. Do not pass this field again when making repeat purchases with an existing token

tokenString(255)Conditional

Business credential token. Pass the corresponding token value by type

CardOnFile: The payment credential returned after successfully saving the card; if the first transaction was processed in `CardOnFile` mode, subsequent repeat purchases using this token must also continue to pass `bizType=CardOnFile`

CodeGrant: The business credential token obtained after signing or authorization is completed

notificationUrlString(255)Optional

A custom address set by the merchant for notifying the transaction result. Once this parameter is filled, PingPongCheckout will asynchronously push the transaction result to this address via POST.
URL recommendation: use a complete URL with a publicly reachable domain name. Standard web ports are recommended (HTTPS defaults to 443 and HTTP defaults to 80). Ensure the URL can reliably receive PingPongCheckout asynchronous notifications.

closeNotificationUrlString(255)Optional

A custom address set by the merchant for notifying the order closure result. Once this parameter is filled, PingPongCheckout will asynchronously push the order closure result to this address via POST.
URL recommendation: use a complete URL with a publicly reachable domain name. Standard web ports are recommended (HTTPS defaults to 443 and HTTP defaults to 80). Ensure the URL can reliably receive PingPongCheckout asynchronous notifications.

requestIdString(64)Required

Unique request number, globally unique

remarkString(255)Optional

Merchant's extended fields, can be used to specify certain parameters, will be returned as is in the response body

tradeCountryString(2)Required

Used to specify the country of the PingPong checkout, by default takes the countries supported by PingPong

merchantSourceString(64)Conditional

Platform identification for site-building platforms, must be passed when integrating a site-building platform. It serves to identify which site-building platform initiated the transaction (Note: Non-site-building platforms do not need to submit this parameter, if you need to pass this parameter, please contact PP technical support for confirmation)

shopperIPString(64)Required

User's IP address for placing the order, supports IPv4 format

languageString(12)Optional

Used to specify the language of the PingPong checkout, defaults to en if not provided. See the appendix Checkout Supported Language List for details

jsGeneratedDataString(256)Conditional

Card payments must integrate the risk control component. Card payments need to pass this, if acquisition fails, an empty string can be passed, without blocking the payment process. By embedding the risk control component provided by pingpong, get the browser-related json string and pass it to this parameter. Used by merchants who interface with the risk control plugin, See 3DS Integration Guide for details

Other Parameters