API Only

约 259 字小于 1 分钟

View as Markdown

2025-03-07

注意

Non-Hosted模式下卡支付必须接入风控组件

Request Body Parameters

application/json

公共请求参数

bizContent

threeDSRequestDataString按条件选
paymentMethodObject必填
customerObject按条件选
goodsArray必填
shippingAddressObject按条件选
billingAddressObject按条件选
browserInfoObject按条件选
deviceObject必填
recurringInfoObject按条件选
merchantRiskIndicatorObject可选
captureDelayHoursint必填
- 0表示立即capture
- -1表示手动capture，调用统一下单API成功之后还需要调用下预授权请款 ,本地支付不支持
timeExpireString(10)可选
关单时间。3分钟到10天（低于3分钟默认取3分钟，高于10天默认取10天）时间戳格式，单位：秒，示例值：1683530496
amountString(12)必填
交易金额说明：
- 交易合规要求：支付金额必须严格等于计算公式，详见金额格式
- 精确位数：和币种有关，请查询附录交易币种
- 计算公式：sum(unitPrice × number) + shippingFee + sum(unitTaxAmount × number) - sum(totalDiscountAmount)
- Klarna 特殊规则：
  - 商品总价必须等于支付金额：sum(goods.unitPrice × goods.number) = amount
  - 运费请添加 shipping-fee 商品项（name 和 description 都设置为 shipping-fee）
详见Klarna-S2S
currencyString(3)必填
交易币种，ISO 4217 三位币种，具体支持币种⻅附录交易币种
merchantTransactionIdString(64)必填
商户网站订单流水号，订单唯一标识，可用于后续订单查询和对账
payResultUrlString(255)按条件选
商户自定义接收重定向的结果URL;3DS验证，银行在线转账或虚拟钱包之类支付方式时，最后需要重定向到商户指定的⻚面地址
merchantRequestBillDescriptorString(22)可选
商家自定义动态账单描述，最长 22 个字符；仅允许英文字母、数字、空白字符及英文符号 , . ( ) - / :，不允许中文或其他特殊符号。不同渠道侧可能会做适当截取。
bizTypeString(12)按条件选
`CardOnFile` 交易模式标识。无论 Hosted 还是 Non-Hosted，首笔绑卡并支付且需按 `CardOnFile` 交易模式处理时传固定值 `CardOnFile`；若首次生成 token 时传入了该值，则后续使用该 token 复购时也需继续传入。普通保存卡交易或仅校验卡号/卡要素时无需传此参数(使用这个值请联系技术支持)
merchantUserIdString(256)按条件选
参数含义：商户网站的用户ID，全局唯一
商户类型必传规则：
- 实物商户：可选
- 游戏虚拟类：与 customer.email 必填其一
- 其他虚拟类：与 customer.email 必填其一
业务模式必传规则：
- 保存卡/记住卡号场景：必填，商户网站的持卡人 ID，用于标识对应持卡人身份并关联其已保存卡信息
- CardOnFile 交易模式：必填，商户网站的持卡人 ID，用于标识对应持卡人身份并关联其已保存卡信息
- CodeGrant 模式：必填，会员ID，用户在商户网站的会员ID
详见必传字段规则
createTokenString(1)按条件选
Y/N,是否创建token。用于控制本次支付成功后是否生成可复用的支付凭证。Non-Hosted 首笔保存卡并需生成支付凭证时传 `Y`；后续使用已有 token 复购时无需再传此字段
tokenString(255)按条件选
业务凭证 token。根据不同类型传入对应值
CardOnFile：保存卡成功后返回的支付凭证；若首笔交易按 `CardOnFile` 交易模式处理，则后续使用该 token 复购时也需继续传 `bizType=CardOnFile`
CodeGrant：签约或授权完成后获取的业务凭证 token

notificationUrlString(255)可选

由商户自定义本次交易结果通知的地址，一旦填写该参数，PingPongCheckout 将通过 POST 方式异步推送交易结果到该地址。
地址建议：请填写基于公网域名的完整 URL，推荐使用标准 Web 端口（HTTPS 默认 443，HTTP 默认 80），并确保该地址可稳定接收 PingPongCheckout 的异步通知。

closeNotificationUrlString(255)可选

由商户自定义本次关单结果通知的地址，一旦填写该参数，PingPongCheckout 将通过 POST 方式异步推送关单结果到该地址。
地址建议：请填写基于公网域名的完整 URL，推荐使用标准 Web 端口（HTTPS 默认 443，HTTP 默认 80），并确保该地址可稳定接收 PingPongCheckout 的异步通知。

requestIdString(64)必填

唯一请求号，全局唯一

remarkString(255)可选

商户扩展字段，可用于指定特定参数，会在响应体中原样返回

tradeCountryString(2)必填

用于指定pingpong收银台国家，默认取pingpong侧支持的国家

merchantSourceString(64)按条件选

建站平台标识，建站平台接入必传。作用是标识这笔交易的是从哪个建站平台发起的（备注：非建站平台无需上送此参数，如需传此参数需要联系PP技术支持进行确认）

shopperIPString(64)必填

用户下单IP，支持 IPv4 格式

languageString(12)可选

用于指定pingpong收银台语言, 不传默认为en。详见附录收银台支持语言列表

jsGeneratedDataString(256)按条件选

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

其他参数

Request Body Example

{
  "accId": "2018092714313010016291",
  "clientId": "2018092714313010016",
  "signType": "SHA256",
  "sign": "898A3CBE981B3E2BF4E2B8D1A817D7E23EF93BC4293993EE545E36F4C87F2E79",
  "version": "1.0",
  "bizContent": {
    "timeExpire": "",
    "paymentMethod": {
      "type": "scheme"
    },
    "tradeCountry": "",
    "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",
    "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",
    "requestId": "t_merchantno",
    "shippingAddress": {
      "city": "Miami",
      "country": "US",
      "postcode": "33131",
      "state": "FL",
      "street": "701 Brickell Avenue, Suite 2700"
    }
  }
}

Responses Body Parameters

application/json

公共返回参数

bizContent

issuerInfoObject可选
paymentMethodObject必填
actionObject必填
cardInfoObject可选
extraParamObject按条件选
transactionIdString必填
PingPong 交易流水号
merchantTransactionIdString(64)必填
网站交易流水号
amountString(12)必填
交易金额，精确位数和币种有关，请查询附录交易币种
transactionTimeString(64)必填
交易发起时间，时间戳
transactionEndingTimeString(64)必填
交易到达终态时间，时间戳
currencyString(3)必填
交易币种，ISO 4217 三位币种，具体支持币种⻅附件交易币种
statusString(32)必填
交易状态：状态幂等
- SUCCESS-成功
- FAILED-失败
- PROCESSING-进行中
remarkString(255)可选
商户扩展字段，可用于指定特定参数，会在响应体中原样返回
requestIdString(64)必填
唯一请求号，全局唯一
exchangedAmountString可选
换汇金额
exchangedCurrencyString可选
换汇币种
tokenString(64)按条件选
保存卡成功后返回的支付凭证，可用于后续基于 token 的支付场景。若首笔交易按 `CardOnFile` 交易模式处理，后续使用该 token 支付时也需继续传 `bizType=CardOnFile`。详见接入概览与方案选择
captureDelayHoursint按条件选
- 0表示立即capture
- -1表示手动capture，调用统一下单API成功之后还需要调用下预授权请款 ,本地支付不支持
payResultUrlString(255)按条件选
商户自定义接收重定向的结果URL;3DS验证，银行在线转账或虚拟钱包之类支付方式时，最后需要重定向到商户指定的⻚面地址
threeDContinueString(32)按条件选
是否需要 3DS (验证处理使用⻛控插件对接的商户使用):
- true:是
- false:否
threeDUnionParamsObject按条件选
3DS 验证参数集合，当交易需要 3DS 验证处理的时候，将该参数的返回值传入 PingPong 提供的插件 js指定的函数中(使用⻛控插件对接的商户使用)

Request Body Example

{
  "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",
    "extraParam": {
      "wxTimeStamp": "1695182276",
      "wxNonceStr": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
      "wxPackage": "prepay_id=wx20230920123456789012345",
      "wxSignType": "RSA",
      "wxPaySign": "ABC123DEF456GHI789JKL012MNO345PQR"
    }
  },
  "clientId": "2023082916070710253",
  "code": "000000",
  "description": "Transaction succeeded",
  "sign": "EFDF7C80DAD9EBB13C29E38D7A5BD57899E7C0B7C7414A45F718240381299B56",
  "signType": "SHA256"
}

Modifications

查询API

API Only

Request Body Parameters

Request Body Example

Responses Body Parameters

Request Body Example