H Honor
EN
DiDi finanzas

Documentation

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

2.7 Refund Simulation

2.7 Refund Simulation

  • Path： /external/refund/trialPlan/v1

  • Method: POST

  • API Description: Before the partner send the refund request, the partner can use this API to simulate the refund to check the relevant fees.

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 Type Field Description Present (M/O/C) Remarks
partnerOrderId String Merchant-side payment document ID M
refundAmount Long Refund amount M Actual refund amount
The amount unit is cents. For example, if it's 99.99 pesos, the value here should be 9999.
Refund Amount = sum (Refund Unit Price * Refund Quantity)
refundType String Refund Type M Enumeration:
PART_REFUND-Partial refund
ALL_REFUND-full refund
currency String Currency M ISO 4217 standard
Mexico MXN
refundTime String Refund time M pattern:yyyy-MM-dd'T'HH:mm:ss.SSSXXX
e.g., '2025-12-08T01:11:33.000+08:00‘. Timezone offset is mandatory.

Request Example

{
    "partnerOrderId": "1e1e51a8-8d38-11ef-b32d-ca3c6358d263",
    "refundAmount": 5000,
    "refundType":"ALL_REFUND",
    "currency": "MXN",
    "refundTime": "2024-10-11T17:10:00.000+08:00"
}

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 Refund order information O
originalFee Long Original cost O Original fee = effective fee + waiver fee
The amount unit is cents. For example, if it's 99.99 pesos, the value here should be 9999.
Example: If the refund has exceeded the free capital occupation period—meaning the user must pay a capital occupation fee—the user must pay the effective fee corresponding to the refunded amount for this refund form. If the user does not need to pay capital occupation fee, then effectiveFee = 0.
effectiveFee Long Effective cost O The amount unit is cents. For example, if it's 99.99 pesos, the value here should be 9999.
The refund amount equals the total cost.
chargeFee Long Fee waiver O The amount unit is cents. For example, if it's 99.99 pesos, the value here should be 9999.
error Object Error O
errorCode String Error code O Enumeration:
AmountNotAllowed – Refund amount does not meet the required conditions
AlreadyRefund – Duplicate refund request
PaylaterRuleRejected – Rejected by Paylater rules
UnpaidOrder – Order has not been paid
NotExistOrder – Order does not exist
errorMessage String Error Code Description O

Response Example

{
    "code": "SUCCESS",
    "message": "SUCCESS",
    "data": {
        "effectiveFee": 0,
        "originalFee": 150,
        "chargeFee": 150
    },
    "error": null
}
Copied successfully