H Honor
EN
DiDi finanzas

Documentation

Provides integration guides, API documentation, testing instructions and other information needed throughout the integration process

2.3 Create Payment Order

2.3 Create Payment Order

  • Path： /external/checkout/v1

  • Method: POST

  • API Description: This API is the main API to create the Order. When the users select the DiDi Paga Después payment method in your checkout page, your system should trigger the Create Payment Order API.

Request Message

Request Headers

Field Name Field Description Parameter Value Present (M/O/C) Remarks
Content-Type Content Type application/json M
Authorization This is the partner’s identity authentication value. Bearer {ACCESS-TOKEN} M For details, please refer to "Part II DiDi BNPL Partner Configuration&Env. Setup".
The partner can get the ACCESS-TOKEN value from the Token API call.
When the access expires, call the Token API again to get the new access token.
X-Paylater-Request-Id uuid uuid.
Example: 550e8400-e29b-41d4-a716-446655440000		 M Mandatory UUID v4 string. DiDi will reject requests with invalid format.

Request Body

Field Name Type Field Description Present (M/O/C) Remarks
partnerUid String Merchant-side user ID M Expect merchant side UID
partnerOrderId String Merchant-side payment order ID (Idempotent Key). M Idempotent Key.
The unique payment serial number generated by the merchant for this specific transaction.
⚠️ CRITICAL FOR OPERATIONS:
This ID must be explicitly visible and searchable within your Customer Service (CS) and Order Management System (OMS).
It will serve as the primary reference number for cross-platform reconciliation, troubleshooting, and handling customer complaints.
Please DO NOT use hidden backend IDs or database primary keys, as this will cause severe friction and high communication costs during CS escalations.
orderCreateTime String Order creation time M This field should represent the exact moment the end-user clicks to place the order (i.e., the original order generation time).
Format: ISO 8601 yyyy-MM-dd'T'HH:mm:ss.SSSXXX. (Note: SSS represents 3-digit milliseconds, and XXX represents the timezone offset).
Timezone: Timezone offset is strictly required. DiDi will automatically normalize this to local time based on the offset provided. Examples:
  • Mexico City Time: 2025-12-08T14:30:15.123-06:00

  • Beijing Time: 2025-12-08T14:30:15.123+08:00
partnerOrderAmount Long Order amount M The actual payment amount after applying all merchant discounts.
Calculation: The raw amount must be multiplied by 100. (Do NOT pass floating-point/decimal numbers).
Currency & Unit: Must correspond to the Mexican Peso (MXN). The required unit is centavos (the minimum currency unit).
Example: > For an order value of 99.99 MXN, the value transmitted must be 9999.
redirectUrl String Redirect URL M After the payment operation is completed on the DiDi Paga Después page, regardless of success or failure, this URL will be parsed and returned.
This is mainly a page-to-page interaction.
It will not verify whether the URL can be redirected.
redirectAppLink String App redirect link C The Link used to wake up and redirect the user back to the Merchant's native APP from the DiDi APP upon payment completion.
Usage Rules:
- If operateSource = APP, this field is Mandatory.
- If operateSource = WEB/WAP, this field is Optional.
Link format:
- Deep Link Formula: [Brand Name][Link]
- Example: globalOneTravel://one/webpage?weburl=https%3A%2F%2Fpay.didiglobal.com%2Fpaga-despues%2Flanding
-> Breakdown:
** Brand name - [globalOneTravel]
** Link - ://one/webpage?weburl=https%3A%2F%2Fpay.didiglobal.com%2Fpaga-despues%2Flanding]
-> Brand Examples:
** Client A: sheme://webview/load?target=https%3A%2F%2Fpay.merchant-b.com%2Fgateway%2Fcallback
expireTime String Expiration time O The expiration time for the payment link.
- Business Logic: If the user fails to click "Confirm Payment" before this timestamp, the order automatically expires.
- Fallback Strategy: If left blank/not provided, DiDi will automatically calculate the expiration time as Current Time + N Hours based on system configurations.
- Format & Timezone: ISO 8601 yyyy-MM-dd'T'HH:mm:ss.SSSXXX. Timezone offset is strictly mandatory.
- Example: 2025-12-08T01:11:33.000-06:00
currency String Currency M Mexico MXN
test Boolean Test order Remark flag. O This field is a Test order remark flag.
****** Testing Environment**
For testing environment, the value should be one of below:
  • doesn't exist: this field doesn't exist.

  • true: it's a testing transaction. The same effect as field empty.


Then, no reconciliation will be performed and DiDi won't clear the money to client.
****** Production Environment**
For production environment, it can only be one of the values below:
  • doesn't exist: this field doesn't exist. This is a production normal transaction.

  • false: this is a production normal transaction.

  • true: This is a testing transaction in production env. This transaction won't be settled and won't be included into the reconciliation file.
extendInfo Object Extended information M
deviceInfo M
deviceId String Device ID C The device identifier used for fraud prevention and credit risk assessment.
  • Business Logic:

  • If operateSource = APP: Mandatory. Must pass the real native hardware identifier (e.g., IDFA/IDFV for iOS, or Android ID/OAID for Android).

  • If operateSource = WEB/WAP: Optional.
androidId String android deviceid O Used for Android device identification.
iosId String ios deviceid O idfa/idfv
Used for IOS device identification.
gps String latitude and longitude coordinates O The real-time geographic coordinates of the end-user at checkout.
ip String Public IP M The public IP address of the end-user at checkout, crucial for anti-fraud regional validation.
Business Logic:
- If operateSource = APP: The current public IP address of the consumer's mobile device.
- If operateSource = WEB/WAP: The current public IP address of the consumer's computer/browser.
CRITICAL:
Do NOT pass your backend server's IP or internal LAN IPs (e.g., 127.0.0.1, 192.168.x.x), as this will cause immediate anti-fraud rejection.
operateSource String Operation source (web page/APP) M The channel or platform context where the end-user initiates the transaction.
Format & Rules: Must match one of the following exact enumeration values:
- WAP: Mobile browser environment (e.g., user opens Shein via Safari or Chrome on a mobile phone without downloading the native app).
- WEB: Desktop or PC browser environment.
- APP: Native mobile application client.
lang String Language O Enumeration value:
en-US
es-MX
If not passed or if the passed value is invalid, defaults to es-MX.
userInfo Object User information M
partnerEmail String Merchant-side user email C Normally, this field is optional.
This field will be mandatory only when your company:
  • can't provide the partnerPhone due to your platform design, and

  • get the approval from DiDi BNPL support team to remove the partnerPhone in the Create Payment Order API.
partnerPhone String User mobile phone number M This is a mandatory field. The field information should be:
1. Best scenario: The phone number from the user last login: The Best one and the easiest one that you can provide.

2. Alternative option: The phone number entered by the user when changing their linked phone.

3. Bottom option: The phone number originally provided during user registration: If this phone number was changed, please updated the new one for DiDi.

This phone number is one of the most important field for the BNPL transaction. And this field is mandatory.
P.S. If your company can't provide this field to DiDi due to some specific reason, please help to contact the DiDi BNPL support team to explain the reason.
phoneCountryCode String User mobile phone number country code M The same rules as field "partnerPhone".
regTime String User registration time C The timestamp when the end-user registered their account on the merchant's platform.
Format: ISO 8601 yyyy-MM-dd'T'HH:mm:ss.SSSXXX. Timezone offset is strictly mandatory.
Example: 2025-12-08T01:11:33.000-06:00
Rules:
This field is Mandatory if newUserFlag is absent.
This field is Optional if newUserFlag is present.
newUserFlag String New user or not C The flag indicating whether the end-user is a newly registered user on the merchant's platform within the last 30 days.
Format & Rules: Enumeration string value:
- 1: New user (registered within the last 30 days).
- 0: Existing user (registered more than 30 days ago).
Rules:
This field is Mandatory if regTime is absent.
This field is Optional if regTime is present.
nickName String User nickname O
userLevel String User rating O The comprehensive user classification or loyalty tier on the merchant's platform.
Free-text string representing the merchant's internal user tiering system.
Example: VIP_LEVEL_3 or PLATINUM_MEMBER or HIGH_CREDIT_SCORE or others.
smeTag Boolean Small business label O Enumeration values: true / false / null
true-the enterprise is a small or micro enterprise.
false-the enterprise is not a small or micro enterprise.
null-no data is available.
lastSuccInstrument String Last successful payment method O The payment instrument used by the user (on the merchant platform) during their last successful transaction.
fees List<Object> Expense item O A detailed list of additional order expenses (e.g., shipping, taxes) used for itemized breakdown display and auditing.
type String Type O The specific category classification of the fee item, currently restricted to the enumeration value POSTAGE (Shipping/Delivery fee).
Enum:
POSTAGE
amount Long Amount of money O The exact financial value of the fee item, represented as a long integer in the currency's smallest unit (e.g., centavos for MXN).
additionalRiskData String additional risk data O Additional risk data
marketingFlag String Marketing Flag O The flag indicating whether marketing promotions, discounts, or campaigns are applied to this transaction.
1 - Marketing
0 - Not marketing
items List<Object> Goods information O If there are multiple quantities of the same SKU, only the quantity needs to be changed.
categoryId String Unique identifier for the goods catalog O
categoryName String Goods catalog name O
skuId String Unique identifier for goods SKU O
skuName String Goods SKU name M goods SKU name
goodsName String User-visible display field O goods Name
unitPrice Long Actual unit price (after discount) O The amount unit is cents. For example, if it's 99.99 pesos, the value here should be 9999.It must be transmitted if it exists.
skuCurrency String Currency O ISO 4217 standard-Mexico MXN
quantity Integer Number O
pictureUrl String Goods picture URL O
shippingAddress String Receiving address O To the street address
shippingAddress2 String Receiving address O To unit address
shippingPostcode String Receipt zip code O
shippingPhoneNumber String Receiving mobile phone number O
shippingPhoneCountryCode String Receiving mobile phone number country code O 52
seller Object Seller information O
sellerId String Unique seller ID C The unique identifier of the actual seller or sub-merchant/store conducting the transaction.
- Platform-model Merchants (e.g., Marketplaces): Strictly mandatory (M) to track individual sub-stores.
- Direct-to-Consumer (DTC) / Direct-sale Merchants: Optional (O).
sellerName String Seller name O
sellerRegTime String Seller registration time O Pattern: yyyy-MM-dd'T'HH:mm:ss.SSSXXX e.g., '2025-12-08T01:11:33.000-06:00' Timezone offset is mandatory.
mccCode String Merchant Category Code C merchant business type.
- Platform-model Merchants (e.g., Marketplaces): Strictly mandatory (M) to track individual sub-stores.
- Direct-to-Consumer (DTC) / Direct-sale Merchants: Optional (O).
type String Goods type O Enumeration value:
PHYSICAL_GOOD
VIRTUAL_GOOD
metadata String Metadata information O DiDi Paga Después will provide this information via the query and order callback
JSON format

Request Example

{
  "partnerUid": "01213121131",
  "partnerOrderId": "ea7ed173-xxxx-11ef-b32d-ca3c6358d263",
  "orderCreateTime": "2026-06-30T14:30:15.123-06:00",
  "partnerOrderAmount": 5000,
  "redirectUrl": "<https://www.merchant.com/h5/orderInfo/index.html>",
  "redirectAppLink": "clientA://one/webpage?weburl=https%3A%2F%2Fapi.merchant-a.com%2Fcheckout%2Fresult",
  "expireTime": "2026-06-30T18:30:15.000-06:00",
  "currency": "MXN",
  "test": true,
  "extendInfo": {
    "deviceInfo": {
      "deviceId": "abcdef123456",
      "androidId": "4af23b10c29d58e1",
      "iosId": "E621E1F8-C36C-495A-93FC-0C247A3E6E5F",
      "gps": "19.4326,-99.1332",
      "ip": "187.137.42.155",
      "operateSource": "APP",
      "lang": "es-MX"
    },
    "userInfo": {
      "partnerEmail": "test@crecmexico.org",
      "partnerPhone": "5522612379",
      "phoneCountryCode": "+52",
      "regTime": "2025-07-12T10:25:06.509-06:00",
      "newUserFlag": "0",
      "nickName": "3wqqw121",
      "userLevel": "VIP_LEVEL_3",
      "smeTag": true,
      "lastSuccInstrument": "SPEI"
    },
    "fees": [
      {
        "type": "POSTAGE-POSTAGE",
        "amount": 100
      }
    ],
    "additionalRiskData": "{}",
    "marketingFlag": "1"
  },
  "items": [
    {
      "categoryId": "mx_mp_001",
      "categoryName": "Electronics",
      "skuId": "mx_mp_phone_001",
      "skuName": "Smartphones",
      "goodsName": "Premium Smartphone 128GB",
      "unitPrice": 4900,
      "skuCurrency": "MXN",
      "quantity": 1,
      "pictureUrl": "<https://img.merchant.com/p/phone001.jpg>",
      "shippingAddress": "Calle la asomada",
      "shippingAddress2": "47 Planta 2",
      "shippingPostcode": "54715",
      "shippingPhoneNumber": "5522612379",
      "shippingPhoneCountryCode": "52",
      "seller": {
        "sellerId": "11312131",
        "sellerName": "test-sell",
        "sellerRegTime": "2024-10-14T02:30:39.000-06:00",
        "mccCode": "5732"
      },
      "type": "PHYSICAL_GOOD"
    }
  ],
  "metadata": "{}"
}

Response Message

Response Header

Field Name Field Description Parameter Value Present (M/O/C) Remarks
Content-Type Content Type application/json M

Response Body

Field Name Type Field Description Present (M/O/C) Remarks
code String Return Code M Enumeration Value:
SUCCESS
FAILED
RATE_LIMIT
INVALID_TOKEN
message String Response Code Description M
data Object Response data O
orderId String Order id M DiDi Paga Después side generation
partnerUid String Merchant-side user ID M
partnerOrderId String Merchant-side payment document ID M
applyLoanId String Apply for loan id O Loan ID in the DiDi Paga Después side credit core system
partnerOrderAmount Long Order amount M The actual payment amount multiplied by 100; this amount is the final amount after applying the merchant’s discount.
The amount unit is cents. For example, if it's 99.99 pesos, the value here should be 9999.
currency String Currency M ISO 4217 standard
Mexico MXN
orderStatus String Order Status M Enumeration:
INIT : Initialize
PENDING: PENDING
PAYING: PAYING
PAID: PAID
CANCELED: CANCELED
EXPIRED: EXPIRED
DENIED: Rejected
rejectCode String Reject Code O Value Existed in DENIED State
Enumeration:
GeneralError–Internal error
PaylaterRuleRejected–Rejected by Paylater rules
RiskRuleRejected–Rejected by risk control rules
OverdueRepayment–The user has overdue payments
CreditNotEnough–Insufficient credit limit
PaylaterRuleDissatisfy–Does not satisfy Paylater rule requirements
RiskControlRejected–Rejected by risk control
TradePayFail-Failed to spend
rejectMsg String Rejection reason O Value Existed in DENIED State
redirectUrl String Redirect URL M After the payment operation is completed on the DiDi Paga Después page, regardless of success or failure, this URL will be parsed and returned.
This is mainly a page-to-page interaction.
It will not verify whether the URL can be redirected.
redirectAppLink String App redirect link O
fuid Long DiDi Paga Después financial member domain user ID O
metadata String Metadata Information O DiDi Paga Después will provide this information via the query and order callback
JSON format
paymentEntryUrl String url redirecting to DiDi Paga Después H5 payment page O
expireTime String Expiration time of this order O pattern:yyyy-MM-dd'T'HH:mm:ss.SSSXXX
e.g., '2025-12-08T01:11:33.000+08:00‘. Timezone offset is mandatory.
finishTime String Completion time O pattern:yyyy-MM-dd'T'HH:mm:ss.SSSXXX
e.g., '2025-12-08T01:11:33.000+08:00‘. Timezone offset is mandatory.
createTime String Order creation time O pattern:yyyy-MM-dd'T'HH:mm:ss.SSSXXX
e.g., '2025-12-08T01:11:33.000+08:00‘. Timezone offset is mandatory.
updateTime String Order status latest update time O pattern:yyyy-MM-dd'T'HH:mm:ss.SSSXXX
e.g., '2025-12-08T01:11:33.000+08:00‘. Timezone offset is mandatory.
orderCreateTime String Merchant-side order creation time O pattern:yyyy-MM-dd'T'HH:mm:ss.SSSXXX
Time zone of Mexico City
e.g., '2025-12-08T01:11:33.000+08:00‘. Timezone offset is mandatory.
test Boolean Test sheet label O
error Object Error O
errorCode String Error code O
errorMessage String Error Code Description O

Response Example

{
    "code": "SUCCESS",
    "message": "SUCCESS",
    "data": {
        "orderId": "189d141e-xxxx-11ef-b32d-ca3c6358d263",
        "partnerUid": "01213121131",
        "partnerOrderId": "1e1e51a8-xxxx-11ef-b32d-ca3c6358d263",
        "partnerOrderAmount": 5000,
        "currency": "MXN",
        "orderStatus": "PENDING",
        "redirectUrl": "<https://www.merchant.com/h5/orderInfo/index.html>",
        "redirectAppLink": "clientA://one/webpage?weburl=https%3A%2F%2Fapi.merchant-a.com%2Fcheckout%2Fresult",
        "fuid": 1231413141,
        "metadata": "{}",
        "paymentEntryUrl": "<https://pay.didiglobal.com/global-bnpl/kyc/?credit_type=full&fuid=1231413141&orderId=189d141e-8d38-11ef-b32d-ca3c6358d263>",
        "expireTime": "2026-06-30T18:26:00.000-06:00",
        "finishTime": null,
        "createTime": "2026-06-30T16:30:39.000-06:00",
        "updateTime": "2026-06-30T16:30:39.000-06:00",
        "orderCreateTime": "2026-06-30T14:30:39.000-06:00",
        "test": true
    },
    "error": null
}
Copied successfully