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.

OpenAPI Viewer

Request Body Parameters

application/json

Common Request Parameters

bizContent

recurringInfoObjectConditional
threeDSRequestDataStringConditional
customerObjectConditional
goodsArrayRequired
shippingAddressObjectConditional
billingAddressObjectConditional
merchantRiskIndicatorObjectOptional
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.

Local payment options available: Non-Hosted Supported APMs
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