Marketplaces API Only (Non-Hosted Mode)

About 86 wordsLess than 1 minute

View as Markdown

2025-07-01

Caution

Card payments under API Only mode must integrate risk control components

Request Body Parameters

application/json

Common Request Parameters

bizContent

threeDSRequestDataStringConditional
paymentMethodObjectRequired
customerObjectConditional
shippingAddressObjectConditional
billingAddressObjectRequired
browserInfoObjectConditional
deviceObjectRequired
subOrderListArrayConditional
captureDelayHoursintRequired
- 0表示立即capture
- -1表示手动capture，调用统一下单API成功之后还需要调用下预授权请款 ,本地支付不支持
timeExpireString(10)Optional
关单时间。3分钟到10天（低于3分钟默认取3分钟，高于10天默认取10天）时间戳格式，单位：秒，示例值：1683530496
amountString(12)Required
交易金额，精确位数和币种有关，请查询附录交易币种。根据交易合规需要，该金额需等于商品金额总和
currencyString(3)Required
交易币种，ISO 4217 三位币种，具体支持币种⻅附录交易币种
merchantTransactionIdString(64)Required
商户网站订单流水号，订单唯一标识，可用于后续订单查询和对账
payResultUrlString(255)Conditional
商户自定义接收重定向的结果URL;3DS验证，银行在线转账或虚拟钱包之类支付方式时，最后需要重定向到商户指定的⻚面地址
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. Pass `null` for guest mode or if it doesn't exist
CodeGrant: Member ID, the 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 extension field, can be used to specify specific parameters, will be returned as is in the response body

tradeCountryString(2)Optional

Used to specify the PingPong checkout counter country, defaults to the countries supported by PingPong

merchantSourceString(64)Conditional

Website platform identifier, required for website platform access. Its purpose is to identify which website platform initiated this transaction (Note: Non-website platforms do not need to send this parameter. If this parameter needs to be sent, please contact PP technical support for confirmation)

shopperIPString(64)Required

User's order IP, supports IPv4 format

languageString(12)Optional

Used to specify the PingPong checkout language, defaults to en if not passed. See appendix Supported Checkout Languages List

merchantUserIdString(256)Conditional

Member ID, the user's member ID on the merchant's website, applicable to fast payment scenarios. Can be omitted for guest users

jsGeneratedDataString(256)Conditional

卡支付必须接入风控组件, 卡支付需要传, 若获取失败，可传空字符串，不阻塞支付流程。通过嵌入pingpong提供的风控组件，获取浏览器相关信息的json字符串，传到这个参数中。使用⻛控插件对接的商户使用，详见3DS集成指南

Other Parameters

请求报文示例

{
  "accId": "2018092714313010016291",
  "clientId": "2018092714313010016",
  "signType": "SHA256",
  "sign": "898A3CBE981B3E2BF4E2B8D1A817D7E23EF93BC4293993EE545E36F4C87F2E79",
  "version": "1.0",
  "bizContent": {
    "timeExpire": "",
    "tradeCountry": "",
    "paymentMethods": [],
    "threeDSRequestData": {
      "executeThreeD": "",
      "authenticationValue": "",
      "acsTransactionId": "",
      "veresEnrolled": "",
      "specificationVersion": "",
      "directoryServerTransactionId": "",
      "threeDSServerTransactionId": "",
      "paresStatus": "",
      "eci": ""
    },
    "browserInfo": {
      "acceptHeader": "content-type=application/x-www-form-urlencoded;accept=*/*;cache-control=no-cache;postman-token=cf489264-5378-4d5d-a86c-72c86a408c03;accept-encoding=gzip, deflate;content-length=588;connection=keep-alive;",
      "colorDepth": "32",
      "jetLag": "480",
      "screenHeight": "1980",
      "screenWidth": "1080",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 Chrome/72.0.3626.121 Safari/537.36",
      "windowSize": "05",
      "javaEnabled": "true",
      "javaScriptEnabled": "true"
    },
    "device": {
      "fingerprintId": "",
      "orderTerminal": "01"
    },
    "jsGeneratedData": {
      "fingerprintId": "2018092714313010016549_PP20210608151727OB",
      "forterSiteId": "e088dda90c4e",
      "forterTokenCookie": "c3402ed6f84d4c50add3458a1ce51d60_1623137756842_87_UDF43_11ck",
      "orderTerminal": "03",
      "threeDSServerTransID": ""
    },
    "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": "123456@gmail.com",
      "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": "t_email",
      "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": "t_merchantno",
    "merchantUserId": "12604896051315",
    "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",
    "requestId": "t_merchantno",
    "shippingAddress": {
      "city": "Miami",
      "country": "US",
      "postcode": "33131",
      "state": "FL",
      "street": "701 Brickell Avenue, Suite 2700"
    }
  }
}

Responses Body Parameters

application/json

Common Response Parameters

bizContent

issuerInfoObjectOptional
paymentMethodObjectRequired
actionObjectRequired
cardInfoObjectOptional
transactionIdStringRequired
PingPong transaction number
merchantTransactionIdString(64)Required
Website transaction number
amountString(12)Required
Transaction amount, the precision and currency type are related, please refer to the appendix Transaction Currencies
transactionTimeString(64)Required
Transaction initiation time, timestamp
transactionEndingTimeString(64)Required
Time when the transaction reaches its final state, timestamp
currencyString(3)Required
Transaction currency, ISO 4217 three-letter code, for supported currencies see attachment Transaction Currencies
statusString(32)Required
Transaction status: Idempotent Status
- SUCCESS - Success
- FAILED - Failed
- PROCESSING - In progress
remarkString(255)Optional
Merchant extended fields, can be used to specify specific parameters, will be returned as is in the response body
requestIdString(64)Required
Unique request number, globally unique
exchangedAmountStringOptional
Exchange amount
exchangedCurrencyStringOptional
Exchange currency
tokenString(64)Conditional
The payment credential returned after successfully saving the card, which can be used for subsequent token-based payment scenarios. If the first transaction was processed in `CardOnFile` mode, subsequent payments using this token must also continue to pass `bizType=CardOnFile`. See Saved Cards and CardOnFile Overview
captureDelayHoursintConditional
- 0 indicates immediate capture
- -1 indicates manual capture, after successfully calling the unified order API, you also need to call Pre-Authorization Capture, local payments do not support this
payResultUrlString(255)Conditional
Merchant-defined URL for receiving redirect results; for 3DS verification, bank online transfer, or virtual wallet payment methods, it finally needs to redirect to the merchant-specified page address
threeDContinueString(32)Conditional
Whether 3DS (verification processing using risk control plugin) is required:
- true: Yes
- false: No
threeDUnionParamsObjectConditional
3DS verification parameter set, when the transaction requires 3DS verification, pass the return value of this parameter into the function specified by the PingPong provided plugin js (used by merchants using the risk control plugin)

请求报文示例

{
  "accId": "2023082916070710253541",
  "bizContent": {
    "issuerInfo": {
      "issuerResultMsg": "Approved or completed successfully",
      "issuerResultCode": "00"
    },
    "remark": "Remark customer defined txt",
    "transactionTime": "1714978654000",
    "requestId": "PMT-LUC4VOQM381714978651450",
    "merchantTransactionId": "PMT-LUC4VOQM381714978651450",
    "currency": "USD",
    "exchangedAmount": "100",
    "exchangedCurrency": "USD",
    "amount": "100.000000",
    "authenticationInfo": {
      "avsResult": "Unknown",
      "cvvResult": "Y",
      "threeDSecure": "N"
    },
    "cardInfo": {
      "firstName": "James",
      "isoCountryA2": "BE",
      "lastName": "LeBron",
      "lastFourDigits": "1002",
      "cardLevel": "",
      "paymentBrand": "MASTERCARD",
      "cardType": "CREDIT",
      "issuringBank": "",
      "firstSixDigits": "520474",
      "isoCountry": "BELGIUM"
    },
    "transactionEndingTime": "1714978655669",
    "threeDUnionParams": {
      "threeDContinue": "false"
    },
    "transactionId": "2024050650046394",
    "threeDContinue": "false",
    "paymentMethod": {
      "type": "scheme"
    },
    "captureDelayHours": 0,
    "status": "SUCCESS"
  },
  "clientId": "2023082916070710253",
  "code": "000000",
  "description": "Transaction succeeded",
  "sign": "EFDF7C80DAD9EBB13C29E38D7A5BD57899E7C0B7C7414A45F718240381299B56",
  "signType": "SHA256"
}

MODIFY PAYMENTS

KYB API

Marketplaces API Only (Non-Hosted Mode)

Request Body Parameters

请求报文示例

Responses Body Parameters

请求报文示例