---
url: >-
  https://acquirer-api-docs-v4-en.pingpongx.com/notes/zh/checkout/api/reserve/index.md
description: >-
  prePay（预下单）接口用于创建支付会话，适用于跳转收银台、内嵌 SDK 等收银台接入场景。关键特性包括通过 merchantTransactionId
  唯一标识一笔交易，一旦创建，该 ID 对应的参数不可更改；若需修改参数，则必须使用新的 merchantTransactionId 重新发起请求。
---
# 收银台预下单

```apidef
endpoint: POST /v4/payment/prePay
name: 收银台预下单
summary: 创建 prePay 预下单会话
tags: Checkout, Payment
```

prePay（预下单）接口用于创建支付会话，适用于跳转收银台、内嵌 SDK 等收银台接入场景。关键特性包括通过 merchantTransactionId 唯一标识一笔交易，一旦创建，该 ID 对应的参数不可更改；若需修改参数，则必须使用新的 merchantTransactionId 重新发起请求。

## 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| accId | string | M | 店铺唯一标识 |
| clientId | string | M | PingPong 商户号 |
| signType | string | M | 支持 MD5 、 SHA256 ，具体⻅本文签名规约: /notes/zh/onlinePayment/developer/sign/一栏 |
| sign | string | M | 签名，具体⻅本文签名规约: /notes/zh/onlinePayment/developer/sign/，所有参数均参与签名 |
| version | string | M | 版本号，当前固定为1.0，后续随接口变动可能有调整 |
| bizContent | string | M | 请求参数的集合，最大长度不限，除公共请求参数外所有请求参数都必须放在这个参数中传递，格式：JSON字符串。该字段内容为 JSON 字符串，反序列化后的结构见 contentSchema。 |
| └─ captureDelayHours | integer | M | 0表示立即capture; -1表示手动capture，调用统一下单API成功之后还需要调用下预授权请款: /notes/zh/checkout/api/modifications/capture/ ,本地支付不支持; |
| └─ timeExpire | string | O | 关单时间。3分钟到10天（低于3分钟默认取3分钟，高于10天默认取10天）时间戳格式，单位：秒，示例值：1683530496 |
| └─ amount | string | M | 交易金额说明： 交易合规要求 ：支付金额必须严格等于计算公式，详见金额格式: /notes/zh/onlinePayment/developer/APIUsage/#amount-format; 精确位数 ：和币种有关，请查询附录交易币种: /notes/zh/appendix/transactionCurrency/; 计算公式 ：sum(unitPrice × number) + shippingFee + sum(unitTaxAmount × number) - sum(totalDiscountAmount); Klarna 特殊规则 ： 商品总价必须 等于 支付金额：sum(goods.unitPrice × goods.number) = amount; 运费请添加 shipping-fee 商品项（name 和 description 都设置为 shipping-fee）; ; 详见Klarna-收银台: /notes/zh/paymentMethods/Klarna/integrationWithCheckout/ |
| └─ currency | string | M | 交易币种，ISO 4217 三位币种，具体支持币种⻅附录交易币种: /notes/zh/appendix/transactionCurrency/ |
| └─ merchantTransactionId | string | M | 商户网站订单流水号，订单唯一标识，可用于后续订单查询和对账 |
| └─ payResultUrl | string | M | 商户自定义接收重定向的结果URL |
| └─ payCancelUrl | string | M | 收银台页面取消支付操作时页面跳转地址 |
| └─ merchantRequestBillDescriptor | string | O | 商家自定义动态名，不同渠道侧会做适当截取（只支持英文和数字） |
| └─ bizType | string | C | `CardOnFile` 交易模式标识。无论 Hosted 还是 Non-Hosted，首笔绑卡并支付且需按 `CardOnFile` 交易模式处理时传固定值 `CardOnFile`；若首次生成 token 时传入了该值，则后续使用该 token 复购时也需继续传入。普通保存卡交易或仅校验卡号/卡要素时无需传此参数(使用这个值请联系技术支持) |
| └─ merchantUserId | string | C | 参数含义： 商户网站的用户ID，全局唯一
商户类型必传规则： 实物商户：可选; 游戏虚拟类：与 customer.email 必填其一; 其他虚拟类：与 customer.email 必填其一; 业务模式必传规则： 保存卡/记住卡号场景： 必填 ，商户网站的持卡人 ID，用于标识对应持卡人身份并关联其已保存卡信息; CardOnFile 交易模式： 必填 ，商户网站的持卡人 ID，用于标识对应持卡人身份并关联其已保存卡信息; CodeGrant 模式： 必填 ，会员ID，用户在商户网站的会员ID; 详见必传字段规则: /notes/zh/onlinePayment/developer/APIUsage/#required-fields |
| └─ recurringInfo | object | C | Apple Pay 订阅信息对象。适用于 bizType=CodeGrant 的订阅场景 |
| └─ └─ recurringPaymentStartDate | string | O | 首笔付款日期。若希望首笔付款作为初始交易的一部分发起，请勿传此字段 |
| └─ └─ recurringPaymentIntervalUnit | string | M | 表示完整扣费周期一部分的日历时间单位，例如 day 、 month 、 year 或 hour |
| └─ └─ recurringPaymentIntervalCount | integer | M | 构成完整扣费周期的间隔单位数量 |
| └─ └─ recurringPaymentEndDate | string | O | 末次付款日期。若无需指定付款结束日期，请勿传此字段 |
| └─ cardToken | string | O | 可选字段。收银台已保存卡的展示基于 `merchantUserId` 关联；仅当同一 `merchantUserId` 下绑定了多张卡，且商户希望本次仅展示其中一张卡时，才将该卡对应的已保存卡记录 token 值通过字段名 `cardToken` 传入。若仅绑定一张卡，则无需上传此字段。可通过绑卡查询接口: /notes/zh/tokenization/cof/bindList/获取该 token 值，适用于 CardOnFile 复购 CVV 收集收银台: /notes/zh/integrate/tokenization/cardOnFileCVV/ 场景 |
| └─ notificationUrl | string | O | 由商户自定义本次交易结果通知的地址，一旦填写该参数，PingPongCheckout 将通过 Post 方式异步推送交易结果到该地址 |
| └─ closeNotificationUrl | string | O | 由商户自定义本次关单结果通知的地址，一旦填写该参数，PingPongCheckout 将通过 Post 方式异步推送关单结果到该地址 |
| └─ remark | string | O | 商户扩展字段，可用于指定特定参数，会在响应体中原样返回 |
| └─ language | string | O | 用于指定pingpong收银台语言, 不传默认为en。详见附录收银台支持语言列表: /notes/zh/appendix/languageCode/ |
| └─ tradeCountry | string | O | 用于指定pingpong收银台国家，默认取pingpong侧支持的国家 |
| └─ merchantSource | string | C | 建站平台标识，建站平台接入必传。作用是标识这笔交易的是从哪个建站平台发起的（ 备注：非建站平台无需上送此参数，如需传此参数需要联系PP技术支持进行确认 ） |
| └─ shopperIP | string | M | 用户下单IP，支持 IPv4 格式 |
| └─ paymentMethods | array | O | 支付方式列表，收银台页面会根据指定的支付方式进行展示。 本地支付方式可选值：Non-Hosted支持的APM: /notes/zh/paymentMethods/overview/; 常见的卡支付方式入下： 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"] |
| └─ threeDSRequestData | string | C | 3DS验证请求参数。沙箱mock规则使用"merchantUserId": "USER_12345"触发强制3DS。 详见3DS集成指南 |
| └─ └─ executeThreeD | string | C | 3ds验证执行策：
Y-强制进行3ds验证，并且使用PingPongCheckout的3ds; depends-是否进行3ds验证交由PingPongCheckout的风控决策决定; external-需要进行3ds验证，但3ds参数有商户自行收集，交由PingPong执行。备注：此选项不适用于收银台; |
| └─ └─ authenticationValue | string | C | 发卡行在客户身份验证后为Visa、American Express、JCB、Diners Club和Discover交易生成的唯一标识符。原始数据以base64为单位。需要将值转换为格式。 |
| └─ └─ acsTransactionId | string | C | 由ACS分配的唯一事务标识符，用于标识单个事务。 |
| └─ └─ veresEnrolled | string | C | 注册检查的结果。此字段可以包含以下值之一：
Y-卡已注册或可注册；您必须进行身份验证。责任转移。; N-未登记卡；进行授权。责任转移。; U-无论何种原因，都无法进行身份验证。没有责任转移; |
| └─ └─ specificationVersion | string | C | 此字段包含用于处理事务的3D Secure版本。例如，1.0.2或2.0.0。 |
| └─ └─ directoryServerTransactionId | string | C | 目录服务器交易ID由万事达目录服务器在认证交易期间生成，并与认证结果一起传递回商家。 |
| └─ └─ threeDSServerTransactionId | string | C | 3DS服务器分配的唯一事务标识符，用于标识单个事务。 |
| └─ └─ paresStatus | string | C | 身份验证检查的原始结果。此字段可以包含以下值之一：
A-已生成身份验证尝试的证明。; N-客户身份验证失败或取消。交易被拒绝。; U-无论何种原因，身份验证都未完成。; Y-客户已成功通过身份验证。; |
| └─ └─ eci | string | C | 对于验证，仅为Visa、American Express、JCB返回数字电子商务指示符（ECI）Diners Club和Discover交易。身份验证失败时缺少字段。此字段包含以下值之一： 01-尝试身份验证（万事达卡）; 02-认证成功（万事达卡）; 05-Successful authentication (Visa, American Express, JCB, UNION PAY, Diners Club, and Discover); 06-尝试身份验证（Visa、American Express、JCB、Diners Club和Discover）; |
| └─ customer | object | C | 客户信息。虚拟数娱行业非必传 |
| └─ └─ firstName | string | C | 用户名称 |
| └─ └─ lastName | string | C | 用户姓氏 |
| └─ └─ email | string | C | 必传规则： 实物商户： 必填; 游戏虚拟类：与 merchantUserId 必填其一; 其他虚拟类：与 merchantUserId 必填其一; 详见必传字段规则: /notes/zh/onlinePayment/developer/APIUsage/#required-fields
用户邮箱 |
| └─ └─ phone | string | C | 用户联系电话 |
| └─ └─ birthDate | string | C | 出生日期，格式为YYYY-MM-DD |
| └─ └─ identificationType | string | C | 用户身份证件类型(特定国家需要，如墨西哥) |
| └─ └─ identificationId | string | C | 用户身份证件号码(特定国家需要，如墨西哥) |
| └─ goods | array | M | 商品信息 |
| └─ └─ name | string | M | 商品名称 |
| └─ └─ description | string | O | 商品描述 |
| └─ └─ sku | string | O | 商品编号，产品SKU |
| └─ └─ unitPrice | string | M | 商品单价 |
| └─ └─ unitTaxAmount | string | C | 单个商品税费，订单总金额包含税费时必填 |
| └─ └─ taxRate | string | O | 税率,非必填 |
| └─ └─ totalDiscountAmount | string | C | 单个商品总优惠金额，订单总金额涉及优惠时必填 |
| └─ └─ number | string | M | 商品购买数量 |
| └─ └─ imgUrl | string | M | 商品主图链接 |
| └─ └─ virtualProduct | string | O | 是否是虚拟产品，虚拟商品（Y/N) |
| └─ └─ itemType | string | O | 商品类型，枚举值：1/2/3，对应含义入下： 1、DIGITAL：数字商品; 2、PHYSICAL：实物商品; 3、SERVICE：服务; |
| └─ shippingAddress | object | C | 必传规则： 实物商户： 必填; 游戏虚拟类：可选; 其他虚拟类：可选; 详见必传字段规则: /notes/zh/onlinePayment/developer/APIUsage/#required-fields
送货地址信息，虚拟商品可以不填 |
| └─ └─ street | string | M | 收货人街道地址 |
| └─ └─ postcode | string | M | 邮政编码 |
| └─ └─ city | string | M | 收货人城市 |
| └─ └─ state | string | M | 收货人省份,美国加拿大地区传二字码，部分地区没有省份可以不填，详见 《国家代码》 |
| └─ └─ country | string | M | 收货人国家,(ISO二字码)⻅附录 《国家代码》 ，人⺠币提现商户必填 |
| └─ └─ district | string | C | 收货人所属区/县 |
| └─ └─ shippingFee | string | C | 运费 |
| └─ billingAddress | object | C | 必传规则： 实物商户： 必填; 游戏虚拟类：可选; 其他虚拟类： 必填; 详见必传字段规则: /notes/zh/onlinePayment/developer/APIUsage/#required-fields
账单信息 |
| └─ └─ street | string | M | 账单人街道地址 |
| └─ └─ postcode | string | M | 邮政编码 |
| └─ └─ city | string | M | 账单人城市 |
| └─ └─ state | string | M | 账单人省份，美国加拿大地区传二字码，部分地区没有省份可以不填 |
| └─ └─ district | string | C | 账单人所属区/县 |
| └─ └─ country | string | M | 账单人国家, (ISO 二字码)⻅附录 《国家代码》: /notes/zh/appendix/countryCode/ |
| └─ merchantRiskIndicator | object | O | 商户风险补充信息对象，用于补充预售/未来履约交易信息 |
| └─ └─ preOrderPurchase | boolean | C | 是否为预售/未来履约交易。示例值： true |
| └─ └─ preOrderType | string | C | 预售/未来履约类型， preOrderPurchase=true 时必填。示例值： futureServiceBooking 。枚举值如下： presaleBeforeRelease ：未正式发售前的预售; madeToOrder ：下单后才开始生产/备货; backorderRestock ：缺货后接受预订，待补货后履约; crowdfundingFulfillment ：众筹达成后再履约; digitalDelayedDelivery ：数字商品/数字权益未来交付; futureServiceBooking ：未来某个时间履约的服务预约; |
| └─ └─ preOrderEstimatedDeliveryDate | string | C | 商户承诺的预计交付日期， preOrderPurchase=true 时必填。时间戳格式，单位：秒，示例值：1683530496 |

### 请求示例

```json
{
  "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\"}}"
}
```

## 响应参数

| 参数名 | 类型 | 说明 |
|--------|------|------|
| accId | string | 店铺唯一标识 |
| clientId | string | PingPong 商户号 |
| signType | string | 支持 MD5 、 SHA256 ，具体⻅本文签名规约: /notes/zh/onlinePayment/developer/sign/一栏 |
| sign | string | 签名，具体⻅本文签名规约: /notes/zh/onlinePayment/developer/sign/，所有参数均参与签名 |
| code | string | 结果状态码，见附录状态码表: /notes/zh/appendix/successCodeList/ |
| description | string | 结果描述 |
| bizContent | string | 业务响应参数。该字段内容为 JSON 字符串，反序列化后的结构见 contentSchema。 |
| └─ transactionId | string | PingPong 交易流水号 |
| └─ merchantTransactionId | string | 商户网站的的交易流水号 |
| └─ amount | string | 交易金额 |
| └─ currency | string | 交易币种 |
| └─ remark | string | 商户扩展字段 |
| └─ token | string | 本次结账请求的唯一标示,用于初始化JS-SDK |
| └─ innerJsUrl | string | JS-SDK的加载地址 |
| └─ paymentUrl | string | PingPong 支付收银台地址 |

### 响应示例

```json
{
  "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"
}
```