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
merchantId	string(64)	Conditional	Merchant ID of the refund owner (sub-merchant). Required when calling with a partner credential on behalf of a sub-merchant; can be omitted with a merchant-owned credential (defaults to the credential owner). Max 64 characters
merchantAppId	string(64)	Conditional	App ID under the owner merchant, used for disambiguation when the owner merchant has multiple authorized apps. Required if the credential covers multiple apps of the owner merchant; can be omitted when only one app is authorized (resolved automatically). Max 64 characters

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.mchTxnId	string	Merchant refund order ID (mirrors mchTxnId from the request)
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)

// Request Body
{
  "mchTxnId": "merchant_refund_123456",
  "paymentTxnId": "P2209141130105863014",
  "type": "PLATFORM",
  "refundAmount": "100.50",
  "mchExtInfo": "{\"reason\": \"customer request\"}"
}

Merchant Refund Example (On-chain refund)

// Request Body
{
  "mchTxnId": "merchant_refund_789012",
  "paymentTxnId": "P2209141130105863015",
  "type": "MERCHANT",
  "txnHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "mchExtInfo": "{\"reason\": \"customer request\"}"
}

Successful Response

{
  "code": "SYS_SUCCESS",
  "message": null,
  "messageDetail": null,
  "data": {
    "refundTxnId": "R2209141130105863014",
    "paymentTxnId": "P2209141130105863014",
    "mchTxnId": "merchant_refund_123456",
    "state": "PENDING",
    "errorMsg": null
  },
  "success": true
}

Failed Response

{
  "code": "SYS_ERROR",
  "message": "System error",
  "messageDetail": "Error details",
  "data": null,
  "success": false
}

Notes

1. 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)

2. Parameter Dependencies

   • PLATFORM type: Must provide refundAmount, no need for txnHash
   • MERCHANT type: Must provide txnHash, refundAmount is optional

3. Refund Processing Flow

   • PLATFORM type: Calls channel API to process refund from custodial account, usually instant
   • MERCHANT type: Validates merchant-provided on-chain refund transaction and marks as successful

4. Idempotency

   • The same mchTxnId can only initiate one refund
   • It is recommended to use a unique identifier with a timestamp as mchTxnId