---
url: >-
  https://acquirer-api-docs-v4-en.pingpongx.com/en/notes/checkout/api/reserve/index.md
description: >-
  The payment order interface is used to create payment orders in Hosted mode.
  It is suitable for scenarios that require hosting the payment process with a
  payment service provider. Key features include uniquely identifying a
  transaction through merchantTransactionId, where parameters corresponding to
  this ID cannot be changed once created; if parameter modifications are needed,
  a new merchantTransactionId must be used to re-initiate the request.
---
# Payment Order Interface

```apidef
endpoint: POST /v4/payment/prePay
name: Payment Order Interface (Hosted Mode)
summary: Create a prePay checkout session
tags: Checkout, Payment
```

The payment order interface is used to create payment orders in Hosted mode. It is suitable for scenarios that require hosting the payment process with a payment service provider. Key features include uniquely identifying a transaction through merchantTransactionId, where parameters corresponding to this ID cannot be changed once created; if parameter modifications are needed, a new merchantTransactionId must be used to re-initiate the request.

## Request Parameters

| Parameter | Type | Required | Description |
|--------|------|------|------|
| accId | string | M | Unique identifier for the store, which will appear in the response message after creation; inputting it means modifying the data |
| clientId | string | M | PingPong Merchant ID |
| signType | string | M | Supports MD5 , SHA256; for details, see the Signature Specification: /en/notes/guide/sign/ section of this document |
| sign | string | M | Signature; for details, see the Signature Specification: /en/notes/guide/sign/ section of this document. All parameters participate in the signature |
| version | string | M | Version number, currently fixed at 1.0, may be adjusted with changes to the interface in the future |
| bizContent | string | M | Collection of request parameters, with no limit on maximum length. Except for common request parameters, all other request parameters must be passed within this parameter, format: JSON string |
| └─ captureDelayHours | integer | M | 0 indicates immediate capture; -1 indicates manual capture, after successfully calling the unified order API, you also need to call Pre-Authorization Capture: /en/notes/checkout/api/modifications/capture/, local payment does not support this; |
| └─ timeExpire | string | O | 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 |
| └─ amount | string | M | Transaction amount, the precision is related to the currency, please refer to the appendix Transaction Currencies: /en/notes/appendix/transactionCurrency/ |
| └─ currency | string | M | Transaction currency, ISO 4217 three-letter code, for specific supported currencies see the appendix Transaction Currencies: /en/notes/appendix/transactionCurrency/ |
| └─ merchantTransactionId | string | M | Merchant website order serial number, unique identifier for the order, can be used for subsequent order inquiries and reconciliation |
| └─ payResultUrl | string | M | Merchant-defined URL for receiving redirect results |
| └─ payCancelUrl | string | M | URL for page redirection when canceling the payment on the checkout page |
| └─ merchantRequestBillDescriptor | string | O | 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. |
| └─ bizType | string | C | `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) |
| └─ merchantUserId | string | C | 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; |
| └─ recurringInfo | object | C | Apple Pay subscription information object. Applicable to subscription scenarios with bizType=CodeGrant |
| └─ └─ recurringPaymentStartDate | string | O | The date of the first payment. To request the first payment as part of the initial transaction, don't include this attribute |
| └─ └─ recurringPaymentIntervalUnit | string | M | The amount of time, in calendar units such as day, month, year, or hour, that represents a fraction of the total payment interval |
| └─ └─ recurringPaymentIntervalCount | integer | M | The number of interval units that make up the total payment interval |
| └─ └─ recurringPaymentEndDate | string | O | The date of the final payment. To specify no payment end date, don't include this attribute |
| └─ cardToken | string | O | 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: /en/notes/onlinePayment/features/tokenization/cardOnFileCVV/ scenario |
| └─ notificationUrl | string | O | 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. |
| └─ closeNotificationUrl | string | O | 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. |
| └─ remark | string | O | Merchant extended fields, can be used to specify particular parameters, which will be returned in the response body as is |
| └─ language | string | O | Used to specify the language of the pingpong checkout, defaults to en if not provided. For details, see the appendix Supported Checkout Languages List: /en/notes/appendix/languageCode/ |
| └─ tradeCountry | string | O | Used to specify the country of the pingpong checkout, defaults to the countries supported by the pingpong side |
| └─ merchantSource | string | C | 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 ) |
| └─ shopperIP | string | M | User's IP for placing the order, supports IPv4 format |
| └─ paymentMethods | array | O | List of payment methods, the checkout page will display according to the specified payment methods. Local payment options available: Non-Hosted Supported APMs: /en/notes/paymentMethods/overview/; 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"] |
| └─ threeDSRequestData | string | C | 3DS verification request parameters. See 3DS Integration Guide for details |
| └─ └─ executeThreeD | string | C | 3DS verification execution policy:\ Y - Force 3DS verification and use PingPongCheckout's 3DS; depends - Whether to perform 3DS verification is decided by PingPongCheckout's risk control decision; external - 3DS verification is required, but 3DS parameters are collected by the merchant, executed by PingPong. Note: This option is not applicable to the checkout; |
| └─ └─ authenticationValue | string | C | A unique identifier generated by the issuing bank for Visa, American Express, JCB, Diners Club, and Discover transactions after customer identity verification. The raw data is in base64 units. Needs to convert the value into the proper format. |
| └─ └─ acsTransactionId | string | C | A unique transaction identifier assigned by the ACS to identify an individual transaction. |
| └─ └─ veresEnrolled | string | C | Result of the enrollment check. This field can contain one of the following values:\ Y - Card is enrolled or can be enrolled; authentication must be performed. Liability shift applies.; N - Unenrolled card; proceed with authorization. Liability shift applies.; U - Authentication cannot be performed for any reason. No liability shift.; |
| └─ └─ specificationVersion | string | C | This field contains the 3D Secure version used to process the transaction. For example, 1.0.2 or 2.0.0. |
| └─ └─ directoryServerTransactionId | string | C | The Directory Server Transaction ID is generated by the Mastercard Directory Server during the authentication transaction and passed back to the merchant along with the authentication result. |
| └─ └─ threeDSServerTransactionId | string | C | A unique transaction identifier assigned by the 3DS server to identify an individual transaction. |
| └─ └─ paresStatus | string | C | Original result of the authentication check. This field can contain one of the following values:\ A - Evidence of an authentication attempt has been generated.; N - Customer authentication failed or was canceled. The transaction is declined.; U - Authentication was not completed for any reason.; Y - The customer has been successfully authenticated.; |
| └─ └─ eci | string | C | For verification, only the numeric e-commerce indicator (ECI) is returned for Visa, American Express, JCB, Diners Club, and Discover transactions. The field is missing in case of authentication failure. This field contains one of the following values:\ 01 - Attempted authentication (Mastercard); 02 - Successful authentication (Mastercard); 05 - Successful authentication (Visa, American Express, JCB, UNION PAY, Diners Club, and Discover); 06 - Attempted authentication (Visa, American Express, JCB, Diners Club, and Discover); |
| └─ customer | object | C | Customer information. Not required for virtual digital entertainment industry |
| └─ └─ firstName | string | C | User's first name |
| └─ └─ lastName | string | C | User's last name |
| └─ └─ email | string | C | User's email |
| └─ └─ phone | string | C | User's contact phone number |
| └─ └─ birthDate | string | C | Date of birth, format YYYY-MM-DD |
| └─ └─ identificationType | string | C | User's ID document type (required for certain countries, such as Mexico) |
| └─ └─ identificationId | string | C | User's ID document number (required for certain countries, such as Mexico) |
| └─ goods | array | M | Product information |
| └─ └─ name | string | M | Product name |
| └─ └─ description | string | O | Product description |
| └─ └─ sku | string | O | Product code, product SKU |
| └─ └─ unitPrice | string | M | Unit price of the product |
| └─ └─ unitTaxAmount | string | C | Tax per item, mandatory if the total order amount includes tax |
| └─ └─ taxRate | string | O | Tax rate, optional |
| └─ └─ totalDiscountAmount | string | C | Total discount amount per item, mandatory if the total order amount involves discounts |
| └─ └─ number | string | M | Quantity of products purchased |
| └─ └─ imgUrl | string | M | Main product image link |
| └─ └─ virtualProduct | string | O | Whether it is a virtual product, virtual goods (Y/N) |
| └─ └─ itemType | string | O | Product type, enumerated values: 1/2/3, corresponding meanings are as follows:\ 1, DIGITAL: Digital products; 2, PHYSICAL: Physical products; 3, SERVICE: Services; |
| └─ shippingAddress | object | C | Shipping address information, not required for virtual products |
| └─ └─ street | string | M | Recipient's street address |
| └─ └─ postcode | string | M | Postal code |
| └─ └─ city | string | M | Recipient's city |
| └─ └─ state | string | M | Recipient's province, for US and Canada regions, enter two-letter codes, some areas without provinces can leave blank, for details see Country Codes |
| └─ └─ country | string | M | Recipient's country, (ISO two-letter code) see appendix Country Codes , mandatory for RMB withdrawal merchants |
| └─ └─ district | string | C | Recipient's district/county |
| └─ └─ shippingFee | string | C | Shipping cost |
| └─ billingAddress | object | C | Billing information |
| └─ └─ street | string | M | Bill recipient's street address |
| └─ └─ postcode | string | M | Postal code |
| └─ └─ city | string | M | Bill recipient's city |
| └─ └─ state | string | M | Bill recipient's province, for US and Canada regions, enter two-letter codes, some areas without provinces can leave blank |
| └─ └─ district | string | C | Bill recipient's district/county |
| └─ └─ country | string | M | Bill recipient's country, (ISO two-letter code) see appendix Country Codes: /en/notes/appendix/countryCode/ |
| └─ merchantRiskIndicator | object | O | Merchant risk supplemental information object, used to provide pre-order or future-fulfillment transaction details |
| └─ └─ preOrderPurchase | boolean | C | Whether this is a pre-order or future-fulfillment transaction. Example value: true |
| └─ └─ preOrderType | string | C | Pre-order or future-fulfillment type. Required when preOrderPurchase=true . Example value: futureServiceBooking . Supported values: presaleBeforeRelease : Pre-sale before the official release; madeToOrder : Production or stocking starts after the order is placed; backorderRestock : Orders are accepted while out of stock and fulfilled after restocking; crowdfundingFulfillment : Fulfillment happens after crowdfunding succeeds; digitalDelayedDelivery : Digital goods or digital entitlements delivered in the future; futureServiceBooking : Service booking to be fulfilled at a future date or time; |
| └─ └─ preOrderEstimatedDeliveryDate | string | C | Merchant-promised estimated delivery date. Required when preOrderPurchase=true . Timestamp format, in seconds. Example value: 1683530496 |

### Request Example

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

## Response Parameters

| Parameter | Type | Description |
|--------|------|------|
| accId | string | Unique store identifier, which will appear in the response message after being added; inputting it means modifying the data |
| clientId | string | PingPong merchant number |
| signType | string | Supports MD5 , SHA256; for details, see the Signature Specification: /en/notes/guide/sign/ section of this document |
| sign | string | Signature; for details, see the Signature Specification: /en/notes/guide/sign/ section of this document. All parameters participate in the signature |
| code | string | Result status code, see the appendix Status Code Table: /en/notes/appendix/successCodeList/ |
| description | string | Result description |
| bizContent | string | Business response parameters |
| └─ transactionId | string | PingPong transaction number |
| └─ merchantTransactionId | string | Merchant website's transaction number |
| └─ amount | string | Transaction amount |
| └─ currency | string | Transaction currency |
| └─ remark | string | Merchant extended field |
| └─ token | string | Unique identifier for this checkout request, used to initialize the JS-SDK |
| └─ innerJsUrl | string | Loading address of the JS-SDK |
| └─ paymentUrl | string | PingPong payment checkout address |

### Response Example

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