收银台预下单

约 297 字小于 1 分钟

View as Markdown

2025-03-07

注意

同一笔支付订单（merchantTransactionId）修改入参发起新的支付请求，还是会取第一次请求传入的参数。如果需要变更入参，则需要修改 merchantTransactionId 重新发起支付请求。

OpenAPI 总览

Request Body Parameters

application/json

公共请求参数

bizContent

recurringInfoObject按条件选
threeDSRequestDataString按条件选
customerObject按条件选
goodsArray必填
shippingAddressObject按条件选
billingAddressObject按条件选
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-收银台
currencyString(3)必填
交易币种，ISO 4217 三位币种，具体支持币种⻅附录交易币种
merchantTransactionIdString(64)必填
商户网站订单流水号，订单唯一标识，可用于后续订单查询和对账
payResultUrlString(255)必填
商户自定义接收重定向的结果URL
payCancelUrlString(255)必填
收银台页面取消支付操作时页面跳转地址
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
详见必传字段规则
cardTokenString(255)可选
可选字段。收银台已保存卡的展示基于 `merchantUserId` 关联；仅当同一 `merchantUserId` 下绑定了多张卡，且商户希望本次仅展示其中一张卡时，才将该卡对应的已保存卡记录 token 值通过字段名 `cardToken` 传入。若仅绑定一张卡，则无需上传此字段。可通过绑卡查询接口获取该 token 值，适用于 CardOnFile 复购 CVV 收集收银台场景
notificationUrlString(255)可选
由商户自定义本次交易结果通知的地址，一旦填写该参数，PingPongCheckout 将通过 POST 方式异步推送交易结果到该地址。
地址建议：请填写基于公网域名的完整 URL，推荐使用标准 Web 端口（HTTPS 默认 443，HTTP 默认 80），并确保该地址可稳定接收 PingPongCheckout 的异步通知。
closeNotificationUrlString(255)可选
由商户自定义本次关单结果通知的地址，一旦填写该参数，PingPongCheckout 将通过 POST 方式异步推送关单结果到该地址。
地址建议：请填写基于公网域名的完整 URL，推荐使用标准 Web 端口（HTTPS 默认 443，HTTP 默认 80），并确保该地址可稳定接收 PingPongCheckout 的异步通知。
remarkString(255)可选
商户扩展字段，可用于指定特定参数，会在响应体中原样返回
languageString(12)可选
用于指定pingpong收银台语言, 不传默认为en。详见附录收银台支持语言列表
tradeCountryString(2)可选
用于指定pingpong收银台国家，默认取pingpong侧支持的国家
merchantSourceString(64)按条件选
建站平台标识，建站平台接入必传。作用是标识这笔交易的是从哪个建站平台发起的（备注：非建站平台无需上送此参数，如需传此参数需要联系PP技术支持进行确认）
shopperIPString(128)必填
用户下单IP，支持 IPv4 格式
paymentMethodsArray可选
支付方式列表，收银台页面会根据指定的支付方式进行展示。
1. 本地支付方式可选值：Non-Hosted支持的APM
2. 常见的卡支付方式入下：
  - 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
传参示例：
"paymentMethods": ["VISA","Mastercard"]

其他参数

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

公共返回参数

bizContent

transactionIdString(64)必填
PingPong 交易流水号
merchantTransactionIdString(64)必填
商户网站的的交易流水号
amountString(12)必填
交易金额
currencyString(3)必填
交易币种
remarkString(255)可选
商户扩展字段
tokenString可选
本次结账请求的唯一标示,用于初始化JS-SDK
innerJsUrlString可选
JS-SDK的加载地址
paymentUrlString必填
PingPong 支付收银台地址

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

查询API

收银台预下单

Request Body Parameters

Request Body Example

Responses Body Parameters

Request Body Example