H Honor
EN
DiDi finanzas

Documentation

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

2.8 Refund

2.8 Refund

  • Path： /external/refund/v1

  • Method: POST

  • API Description: This API is for partner to refund the transaction. It can be used in either customer-initiated or system-initiated scenarios.

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
partnerOrderId String Merchant-side payment document ID M
partnerRefundId String Merchant-side refund form ID M Idempotent key
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",
    "partnerRefundId": "f0136e12-8d3f-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
partnerRefundId String Merchant-side refund form ID M
partnerOrderId String Original merchant-side payment document ID M
orderId String Original 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-xxxx-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