H Honor
EN
DiDi finanzas

Documentation

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

2.2 Prescreen

2.2 Prescreen

  • Path： /external/prescreen/v1

  • Method: POST

  • API Description: The partner can use this API to check if the user can use the DiDi Paga Después payment method. If the result = SUCCESS is returned, it means that the DiDi Paga Después payment method can be used for this user. This is for users to pre-check whether they have permission to use DiDi BNPL.

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.
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.
currency String Currency M Mexico MXN
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-POSTAGE (Shipping/Delivery fee).
Enum:
POSTAGE-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",
  "partnerOrderAmount": 5000,
  "currency": "MXN",
  "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
error Object Error O
errorCode String Error code O Enumeration:
IllegalParams–Parameter exception
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
errorMessage String Error code description O

Response Example

{
  "code": "SUCCESS",
  "message": "SUCCESS",
  "error": null
}
Copied successfully