Create Refund
Request Method and Path
POST /payin/v1/createRefund
Request Headers
| Field Name | Type | Required | Description |
|---|---|---|---|
| content-type | string | Yes | application/json |
| x-api-key | string | Yes | Provided by Paydify, same as appId |
| x-api-timestamp | string | Yes | Timestamp in milliseconds |
| x-api-signature | string | Yes | Signature, see Signature Algorithm |
Request Body
| Field Name | Type | Required | Description |
|---|---|---|---|
| mchTxnId | string(60) | Yes | Merchant order ID |
| paymentTxnId | string(30) | Yes | Payment order ID |
| type | string | Yes | Refund responsibility: - MERCHANT: Merchant handles refund (on-chain refund), requires txnHash- PLATFORM: Platform handles refund (API/custodial wallet), requires refundAmount |
| refundAmount | string(32) | Conditional | Refund amount (USDT) - PLATFORM type: Required- MERCHANT type: Optional, will fetch from on-chain transaction if not provided |
| txnHash | string(120) | Conditional | Blockchain refund transaction hash - PLATFORM type: Not required- MERCHANT type: Required |
| mchExtInfo | string(512) | No | Merchant extension information, JSON string |
Response Headers
| Field Name | Type | Required | Description |
|---|---|---|---|
| x-api-key | string | Yes | Provided by Paydify, same as appId |
| x-api-timestamp | string | Yes | Timestamp in milliseconds |
| x-api-signature | string | Yes | Signature, see Signature Algorithm |
Response
| Field Name | Type | Description |
|---|---|---|
| code | string | Response code, SYS_SUCCESS indicates success |
| message | string | Response message |
| messageDetail | string | Detailed response message |
| success | boolean | Whether the request was successful |
| data.refundTxnId | string | Paydify refund order ID |
| data.paymentTxnId | string | Associated payment order ID |
| data.state | string | Refund status, enum values see Refund Status |
| data.errorMsg | string | Refund failure reason description |
Examples
Platform Refund Example (Gate.io and other custodial models)
json
// Request Body
{
"mchTxnId": "merchant_refund_123456",
"paymentTxnId": "P2209141130105863014",
"type": "PLATFORM",
"refundAmount": "100.50",
"mchExtInfo": "{\"reason\": \"customer request\"}"
}// Request Body
{
"mchTxnId": "merchant_refund_123456",
"paymentTxnId": "P2209141130105863014",
"type": "PLATFORM",
"refundAmount": "100.50",
"mchExtInfo": "{\"reason\": \"customer request\"}"
}Merchant Refund Example (On-chain refund)
json
// Request Body
{
"mchTxnId": "merchant_refund_789012",
"paymentTxnId": "P2209141130105863015",
"type": "MERCHANT",
"txnHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
"mchExtInfo": "{\"reason\": \"customer request\"}"
}// Request Body
{
"mchTxnId": "merchant_refund_789012",
"paymentTxnId": "P2209141130105863015",
"type": "MERCHANT",
"txnHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
"mchExtInfo": "{\"reason\": \"customer request\"}"
}Successful Response
json
{
"code": "SYS_SUCCESS",
"message": null,
"messageDetail": null,
"data": {
"refundTxnId": "R2209141130105863014",
"paymentTxnId": "P2209141130105863014",
"state": "pending",
"errorMsg": null
},
"success": true
}{
"code": "SYS_SUCCESS",
"message": null,
"messageDetail": null,
"data": {
"refundTxnId": "R2209141130105863014",
"paymentTxnId": "P2209141130105863014",
"state": "pending",
"errorMsg": null
},
"success": true
}Failed Response
json
{
"code": "SYS_ERROR",
"message": "System error",
"messageDetail": "Error details",
"data": null,
"success": false
}{
"code": "SYS_ERROR",
"message": "System error",
"messageDetail": "Error details",
"data": null,
"success": false
}Notes
The type parameter must match the fund custody type of the original payment order
- For custodial payments (e.g., Gate.io), use
type=PLATFORM(platform handles refund) - For non-custodial payments (e.g., BGW, third-party wallets), use
type=MERCHANT(merchant handles refund)
- For custodial payments (e.g., Gate.io), use
Parameter Dependencies
PLATFORMtype: Must providerefundAmount, no need fortxnHashMERCHANTtype: Must providetxnHash,refundAmountis optional
Refund Processing Flow
PLATFORMtype: Calls channel API to process refund from custodial account, usually instantMERCHANTtype: Validates merchant-provided on-chain refund transaction and marks as successful
Idempotency
- The same
mchTxnIdcan only initiate one refund - It is recommended to use a unique identifier with a timestamp as
mchTxnId
- The same