Payment Order Interface (Hosted Mode)

About 219 wordsLess than 1 minute

2025-03-07

Note

Modifying input parameters for the same payment order (merchantTransactionId) and initiating a new payment request will still use the parameters from the first request. If you need to change the input parameters, you must modify the merchantTransactionId and re-initiate the payment request.

POST

📍How to choose a site? See API Endpoint Guide

OpenAPI Viewer

Request Body Parameters

application/json

Common Request Parameters

bizContent

recurringInfoObjectConditional
Apple Pay subscription information object. Applicable to subscription scenarios with bizType=CodeGrant
- recurringPaymentStartDateDatetimeOptional
  The date of the first payment. To request the first payment as part of the initial transaction, don't include this attribute
- recurringPaymentIntervalUnitStringRequired
  The amount of time, in calendar units such as day, month, year, or hour, that represents a fraction of the total payment interval
- recurringPaymentIntervalCountIntegerRequired
  The number of interval units that make up the total payment interval
- recurringPaymentEndDateDatetimeOptional
  The date of the final payment. To specify no payment end date, don't include this attribute
threeDSRequestDataStringConditional
3DS verification request parameters. See 3DS Integration Guide for details
- executeThreeDStringConditional
  3DS verification execution policy:\
  Y - Force 3DS verification and use PingPongCheckout's 3DS
  depends - Whether to perform 3DS verification is decided by PingPongCheckout's risk control decision
  external - 3DS verification is required, but 3DS parameters are collected by the merchant, executed by PingPong. Note: This option is not applicable to the checkout
- authenticationValueStringConditional
  A unique identifier generated by the issuing bank for Visa, American Express, JCB, Diners Club, and Discover transactions after customer identity verification. The raw data is in base64 units. Needs to convert the value into the proper format.
- acsTransactionIdStringConditional
  A unique transaction identifier assigned by the ACS to identify an individual transaction.
- veresEnrolledStringConditional
  Result of the enrollment check. This field can contain one of the following values:\
  Y - Card is enrolled or can be enrolled; authentication must be performed. Liability shift applies.
  N - Unenrolled card; proceed with authorization. Liability shift applies.
  U - Authentication cannot be performed for any reason. No liability shift.
- specificationVersionStringConditional
  This field contains the 3D Secure version used to process the transaction. For example, 1.0.2 or 2.0.0.
- directoryServerTransactionIdStringConditional
  The Directory Server Transaction ID is generated by the Mastercard Directory Server during the authentication transaction and passed back to the merchant along with the authentication result.
- threeDSServerTransactionIdStringConditional
  A unique transaction identifier assigned by the 3DS server to identify an individual transaction.
- paresStatusStringConditional
  Original result of the authentication check. This field can contain one of the following values:\
  A - Evidence of an authentication attempt has been generated.
  N - Customer authentication failed or was canceled. The transaction is declined.
  U - Authentication was not completed for any reason.
  Y - The customer has been successfully authenticated.
- eciStringConditional
  For verification, only the numeric e-commerce indicator (ECI) is returned for Visa, American Express, JCB, Diners Club, and Discover transactions. The field is missing in case of authentication failure. This field contains one of the following values:\
  01 - Attempted authentication (Mastercard)
  02 - Successful authentication (Mastercard)
  05 - Successful authentication (Visa, American Express, JCB, UNION PAY, Diners Club, and Discover)
  06 - Attempted authentication (Visa, American Express, JCB, Diners Club, and Discover)
customerObjectConditional
Customer information. Not required for virtual digital entertainment industry
- firstNameString(24)Conditional
  User's first name
- lastNameString(24)Conditional
  User's last name
- emailString(128)Conditional
  User's email
- phoneString(20)Conditional
  User's contact phone number
- birthDateString(10)Conditional
  Date of birth, format YYYY-MM-DD
- identificationTypeString(20)Conditional
  User's ID document type (required for certain countries, such as Mexico)
- identificationIdString(20)Conditional
  User's ID document number (required for certain countries, such as Mexico)
goodsArrayRequired
Product information
- nameString(128)Required
  Product name
- descriptionString(255)Optional
  Product description
- skuString(255)Optional
  Product code, product SKU
- unitPriceString(12)Required
  Unit price of the product
- unitTaxAmountStringConditional
  Tax per item, mandatory if the total order amount includes tax
- taxRateStringOptional
  Tax rate, optional
- totalDiscountAmountStringConditional
  Total discount amount per item, mandatory if the total order amount involves discounts
- numberString(12)Required
  Quantity of products purchased
- imgUrlString(255)Required
  Main product image link
- virtualProductString(1)Optional
  Whether it is a virtual product, virtual goods (Y/N)
- itemTypeString(1)Optional
  Product type, enumerated values: 1/2/3, corresponding meanings are as follows:\
  1, DIGITAL: Digital products
  2, PHYSICAL: Physical products
  3, SERVICE: Services
shippingAddressObjectConditional
Shipping address information, not required for virtual products
- streetString(256)Required
  Recipient's street address
- postcodeString(16)Required
  Postal code
- cityString(50)Required
  Recipient's city
- stateString(128)Required
  Recipient's province, for US and Canada regions, enter two-letter codes, some areas without provinces can leave blank, for details see Country Codes
- countryString(64)Required
  Recipient's country, (ISO two-letter code) see appendix Country Codes, mandatory for RMB withdrawal merchants
- districtStringConditional
  Recipient's district/county
- shippingFeeStringConditional
  Shipping cost
billingAddressObjectConditional
Billing information
- streetString(256)Required
  Bill recipient's street address
- postcodeString(16)Required
  Postal code
- cityString(50)Required
  Bill recipient's city
- stateString(128)Required
  Bill recipient's province, for US and Canada regions, enter two-letter codes, some areas without provinces can leave blank
- districtStringConditional
  Bill recipient's district/county
- countryString(64)Required
  Bill recipient's country, (ISO two-letter code) see appendix Country Codes
merchantRiskIndicatorObjectOptional
Merchant risk supplemental information object, used to provide pre-order or future-fulfillment transaction details
- preOrderPurchaseBooleanConditional
  Whether this is a pre-order or future-fulfillment transaction. Example value: true
- preOrderTypeString(64)Conditional
  Pre-order or future-fulfillment type. Required when preOrderPurchase=true. Example value: futureServiceBooking. Supported values:
  presaleBeforeRelease: Pre-sale before the official release
  madeToOrder: Production or stocking starts after the order is placed
  backorderRestock: Orders are accepted while out of stock and fulfilled after restocking
  crowdfundingFulfillment: Fulfillment happens after crowdfunding succeeds
  digitalDelayedDelivery: Digital goods or digital entitlements delivered in the future
  futureServiceBooking: Service booking to be fulfilled at a future date or time
- preOrderEstimatedDeliveryDateString(10)Conditional
  Merchant-promised estimated delivery date. Required when preOrderPurchase=true. Timestamp format, in seconds. Example value: 1683530496
captureDelayHoursintRequired
- 0 indicates immediate capture
- -1 indicates manual capture, after successfully calling the unified order API, you also need to call Pre-Authorization Capture, local payment does not support this
timeExpireString(10)Optional
Order closing 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 the appendix Transaction Currencies
merchantTransactionIdString(64)Required
Merchant website order serial number, unique identifier for the order, can be used for subsequent order inquiries and reconciliation
payResultUrlString(255)Required
Merchant-defined URL for receiving redirect results
payCancelUrlString(255)Required
URL for page redirection when canceling the payment on the checkout page
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
User ID, mandatory for CardOnFile or CodeGrant mode
- CardOnFile: The cardholder's ID on the merchant's website, globally unique, used to identify the cardholder and associate stored card information; pass `null` for guest mode or non-existence
- CodeGrant: Member ID, the user's member ID on the merchant's website
cardTokenString(255)Optional
Optional field. The checkout displays stored cards based on `merchantUserId`. Pass the stored-card record token under the field name `cardToken` only when multiple cards are bound under the same `merchantUserId` and the merchant wants to display just one of them in this payment. If only one card is bound, do not pass this field. The token value can be obtained through the bind-list API and is used in the CardOnFile repeat-purchase CVV collection checkout scenario
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.
remarkString(255)Optional
Merchant extended fields, can be used to specify particular parameters, which will be returned in the response body as is
languageString(12)Optional
Used to specify the language of the pingpong checkout, defaults to en if not provided. For details, see the appendix Supported Checkout Languages List
tradeCountryString(2)Optional
Used to specify the country of the pingpong checkout, defaults to the countries supported by the pingpong side
merchantSourceString(64)Conditional
Platform identifier for site building, mandatory for platform integration. It serves to identify from which site-building platform the transaction was initiated (Note: Non-site building platforms do not need to submit this parameter, if needing to send this parameter, contact PP technical support for confirmation)
shopperIPString(128)Required
User's IP for placing the order, supports IPv4 format
paymentMethodsArrayOptional
List of payment methods, the checkout page will display according to the specified payment methods.
1. Local payment options available: Non-Hosted Supported APMs
2. Common card payment methods are as follows:
  - VISA
  - Mastercard
  - DinersClub
  - Discover
  - American Express
  - JCB
  - CMR Falabella
  - Tarjeta Naranja
  - Tarjeta Shopping
  - Nativa
  - Cencosud
  - Cabal
  - Argencard
  - Cordial
  - Cordobesa
  - Elo
  - Hipercard
  - Presto
  - Magna
  - Aura
  - Cartao MercadoLivre
Example of parameter passing:
"paymentMethods": ["VISA","Mastercard"]

Other Parameters

Request Body Example

{
  "accId": "2018092714313010016291",
  "clientId": "2018092714313010016",
  "signType": "SHA256",
  "sign": "28178F3C0B0AF10343F715211B9C7791AB4CF091EB4580505E053318E8F37B85",
  "version": "1.0",
  "bizContent": {
    "timeExpire": "",
    "tradeCountry": "",
    "paymentMethods": [],
    "threeDSRequestData": {
      "executeThreeD": "",
      "authenticationValue": "",
      "acsTransactionId": "",
      "veresEnrolled": "",
      "specificationVersion": "",
      "directoryServerTransactionId": "",
      "threeDSServerTransactionId": "",
      "paresStatus": "",
      "eci": ""
    },
    "shopperIP": "222.126.52.24",
    "captureDelayHours": 0,
    "language": "en",
    "airline": {
      "adultsNumber": "1",
      "aircraftCabinType": "FIRST CLASS",
      "airlineCompanyID": "CA006",
      "airlinePnr": "{dhsalh}",
      "arrivalCity": "Adm",
      "arrivalCountry": "DK",
      "arrivalTime": "201912012010",
      "arrivalTimezone": "UTC+8",
      "babyNumber": "0",
      "bestFare": "Y",
      "bookChannel": "Y",
      "changedTakeoffTime": "",
      "childrenNumber": "0",
      "connectingCity": "",
      "connectionTicket": "N",
      "contactEmail": "t_email",
      "contactName": "James LeBron",
      "contactPhone": "3055787342",
      "flightNumber": "CA006122",
      "freeChange": "Y",
      "frequentFlyerNumber": "CA00612254651B",
      "haveChanged": "N",
      "hotel": {
        "bookNumber": "1",
        "bookRange": "2",
        "checkInDate": "201912010020",
        "city": "Adm",
        "country": "DK",
        "customerName": "James LeBron",
        "name": "AdmHotel",
        "refundPolicy": "FREE CANCELLATION",
        "star": "5"
      },
      "ifConnectingFlight": "N",
      "ifRoundtripFlight": "Y",
      "insurance": "Y",
      "leaveRange": "Y",
      "passengers": [
        {
          "birthday": "1991120",
          "firstName": "James",
          "identificationId": "331081199112012361",
          "identificationType": "ID",
          "lastName": "LeBron",
          "nationality": "US",
          "phone": "3055787342"
        }
      ],
      "productType": "TICKET",
      "routeType": "SINGLE",
      "takeoffCity": "Birmingham",
      "takeoffCountry": "US",
      "takeoffTime": "201912012010",
      "takeoffTimezone": "UTC+8",
      "thirdPartyBook": "N",
      "tripType": "SINGLE",
      "valueAdded": "N"
    },
    "amount": "100",
    "billingAddress": {
      "city": "Birmingham",
      "country": "US",
      "postcode": "35222",
      "state": "AL",
      "street": "1986 Broad Street"
    },
    "carRental": {
      "childrenNumber": "1",
      "discountAmount": "120",
      "discountType": "15%",
      "email": "t_email",
      "firstName": "James",
      "identificationId": "331081199112012361",
      "identificationType": "ID",
      "insuranceLimit": "8000",
      "insuranceType": "RS",
      "lastName": "Lebron",
      "model": "SUV",
      "nationality": "US",
      "personNumber": "3",
      "phone": "3055787342",
      "purchasedInsurance": "Y",
      "rentCity": "Birmingham",
      "rentCountry": "US",
      "rentTime": "201912200320",
      "rentalCompany": "US",
      "returnCity": "Birmingham",
      "returnCountry": "US",
      "returnTime": "201201200320"
    },
    "currency": "USD",
    "customer": {
      "email": "123456@gmail.com",
      "firstName": "James",
      "lastName": "LeBron",
      "identificationId": "",
      "identificationType": "ID",
      "phone": "3055787343",
      "birthDate": ""
    },
    "eCommerce": {
      "freeShipping": "N",
      "shippingMethod": "SEA",
      "shippingFee": ""
    },
    "goods": [
      {
        "description": "short legs",
        "imgUrl": "http://pic.bizhi360.com/bpic/30/5230.jpg",
        "name": "corgi",
        "number": "1",
        "sku": "20230524001",
        "unitPrice": "22",
        "virtualProduct": "N"
      },
      {
        "description": "stupid nerd",
        "imgUrl": "http://d.paper.i4.cn/max/2016/12/08/11/1481166973148_375716.jpg",
        "name": "husky",
        "number": "1",
        "sku": "20230524002",
        "unitPrice": "22",
        "virtualProduct": "N"
      }
    ],
    "merchantTransactionId": "{{merchantTransactionId}}",
    "merchantUserId": "12604896051315",
    "merchantRiskIndicator": {
      "preOrderPurchase": true,
      "preOrderType": "futureServiceBooking",
      "preOrderEstimatedDeliveryDate": "1683530496"
    },
    "notificationUrl": "https://test-acquirer-payment.pingpongx.com/qa/notify",
    "payCancelUrl": "https://test-acquirerpay.pingpongx.com/qa/cancel.html",
    "payResultUrl": "https://test-acquirerpay.pingpongx.com/qa/result.html",
    "reCharge": {
      "accountId": "775330",
      "accountName": "von",
      "gameCategory": "OTHERS",
      "gameName": "Over Watched",
      "gameTerminal": "PC",
      "platformCategory": "N",
      "serverCountry": "US",
      "type": "GAME RECHARGE"
    },
    "remark": "Remark customer defined txt",
    "shippingAddress": {
      "city": "Miami",
      "country": "US",
      "postcode": "33131",
      "state": "FL",
      "street": "701 Brickell Avenue, Suite 2700"
    }
  }
}

Responses Body Parameters

application/json

Common Response Parameters

bizContent

transactionIdString(64)Required
PingPong transaction number
merchantTransactionIdString(64)Required
Merchant website's transaction number
amountString(12)Required
Transaction amount
currencyString(3)Required
Transaction currency
remarkString(255)Optional
Merchant extended field
tokenStringOptional
Unique identifier for this checkout request, used to initialize the JS-SDK
innerJsUrlStringOptional
Loading address of the JS-SDK
paymentUrlStringRequired
PingPong payment checkout address

Request Body Example

{
  "accId": "2018092714313010016291",
  "bizContent": {
    "amount": "1000",
    "paymentUrl": "https://sandbox-acquirer-payment-ssr.pingpongx.com/v3/checkout?token=EU:vr_YVR8u7rn7C1gG97DOg9_-Y66ubtNtoayJ_wiEEzdCnxCHYIk0pXordJYBjq1g",
    "transactionId": "2023092050004591",
    "token": "EU:vr_YVR8u7rn7C1gG97DOg9_-Y66ubtNtoayJ_wiEEzdCnxCHYIk0pXordJYBjq1g",
    "merchantTransactionId": "PMT-PR5GFUNZQP1695182276082",
    "currency": "USD",
    "innerJsUrl": "https://paycdn.pingpongx.com/production/static/sdk/ppPay.min.js?token=EU:vr_YVR8u7rn7C1gG97DOg9_-Y66ubtNtoayJ_wiEEzdCnxCHYIk0pXordJYBjq1g"
  },
  "clientId": "2018092714313010016",
  "code": "000000",
  "description": "Transaction succeeded",
  "sign": "337DE4525BECC73D56E262E04CCCC210C7BA70C78D48DA3BB128E4FEC6D01561",
  "signType": "SHA256"
}

Modifications

Query API

Payment Order Interface (Hosted Mode)

Request Body Parameters

Request Body Example

Responses Body Parameters

Request Body Example