H Honor
EN
DiDi finanzas

Documentation

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

2.9 Refund Query

2.9 Refund Information Query

  • Path：/external/refund/query/v1

  • Method: POST

  • API Description: This is the API for partner to query the refund information, especially the refund status.

  • Usage:Sometimes, the refund information query API might return the error due to the some unpredictable reasons. The partner should not regard the error of query API as the Refund result. The partner should use the specific result returned in query API as the Refund result.

  • Supplementary Instruction: Although the DiDi will send the Webhook to the partner, the Query API is mandatory. This is a fallback (backstop) strategy for the partner to retrieve the Refund status in case the Webhook delivered unsuccessfully..

Request Message

Request Header

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
partnerRefundId String Merchant-side refund form ID M

Request Example

{
    "partnerRefundId": "f0136e12-8d3f-11ef-b32d-ca3c6358d263"
}

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
partnerRefundId String Merchant-side refund form ID M
partnerOrderId String Merchant-side payment document ID M
orderId String Order id O Create payment order API on DiDi Paga Después side
refundId String Refund id O DiDi Paga Después-side generation
partnerUid String Merchant-side user ID O
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.
refundType String Refund Type O Enumeration:
PART_REFUND-Partial refund
ALL_REFUND-full refund
currency String Currency O ISO 4217 standard
Mexico MXN
refundStatus String Refund Status O Enumeration:
INIT: Initialize
PENDING: Processing
SUCCESS:SUCCESS
FAILED: FAILED
rejectCode String Reject 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
rejectMsg String Rejection reason O
refundTime String Refund 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 Refund 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 Refund 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.
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": {
        "partnerOrderId": "1e1e51a8-8d38-11ef-b32d-ca3c6358d263",
        "partnerRefundId": "f0136e12-8d3f-11ef-b32d-ca3c6358d263",
        "orderId": "189d141e-8d38-11ef-b32d-ca3c6358d263",
        "refundId": "1658fd86-8d41-11ef-b32d-ca3c6358d263",
        "partnerUid": "01213121131",
        "refundAmount": 5000,
        "refundType":"ALL_REFUND",
        "currency": "MXN",
        "refundStatus": "INIT",
        "rejectCode": null,
        "rejectMsg": null,
        "refundTime": "2024-10-14T16:30:39.000+08:00",
        "createTime": "2024-10-14T16:30:39.000+08:00",
        "updateTime": "2024-10-14T16:30:39.000+08:00",
        "test": true
    },
    "error": null
}
Copied successfully