Skip to main content

​
Refund Management Schemas

API endpoints for processing refunds and handling payment reversals.

​
Endpoints

MethodEndpointDescription
POST/v1/refunds/initiateInitiate refund for transaction
GET/v1/refunds/:refundId/statusGet refund status

​
POST /v1/refunds/initiate

Initiate a refund for a completed transaction.

​
Request Body

{
  "transactionId": "string",
  "amount": 25.0,
  "reason": "string",
  "refundType": "full | partial",
  "metadata": {}
}

​
Request Schema

FieldTypeRequiredDescription
transactionIdstringYesOriginal transaction ID
amountnumberYesRefund amount
reasonstringYesReason for refund
refundTypestringYesType of refund (full or partial)
metadataobjectNoAdditional metadata

​
Response Schema

{
  "statusCode": 201,
  "success": true,
  "message": "Refund initiated successfully",
  "data": {
    "refundId": "string",
    "status": "pending | processing | completed",
    "estimatedProcessingTime": "string"
  }
}

​
Response Fields

FieldTypeDescription
refundIdstringUnique refund identifier
statusstringCurrent refund status
estimatedProcessingTimestringEstimated processing time

​
GET /v1/refunds/:refundId/status

Get the current status and details of a refund.

​
Path Parameters

ParameterTypeRequiredDescription
refundIdstringYesRefund identifier

​
Response Schema

{
  "statusCode": 200,
  "success": true,
  "message": "Refund status retrieved successfully",
  "refund": {
    "refundId": "string",
    "originalTransactionId": "string",
    "amount": 25.0,
    "originalAmount": 50.0,
    "currency": "string",
    "status": "pending | processing | completed | failed",
    "refundType": "full | partial",
    "reason": "string",
    "initiatedBy": "string",
    "processedAt": "string",
    "createdAt": "string",
    "updatedAt": "string"
  }
}

​
Refund Schema

FieldTypeDescription
refundIdstringUnique refund identifier
originalTransactionIdstringOriginal transaction ID
amountnumberRefund amount
originalAmountnumberOriginal transaction amount
currencystringCurrency code
statusstringRefund status
refundTypestringType of refund
reasonstringRefund reason
initiatedBystringWho initiated the refund
processedAtstringProcessing timestamp
createdAtstringCreation timestamp
updatedAtstringLast update timestamp

​
Refund Status Types

StatusDescription
pendingRefund initiated, awaiting processing
processingRefund is being processed by bank
completedRefund successfully processed
failedRefund failed or was rejected
cancelledRefund was cancelled

​
Refund Types

TypeDescription
fullComplete refund of transaction amount
partialPartial refund of transaction amount

​
Error Responses

​
400 Bad Request

{
  "statusCode": 400,
  "success": false,
  "message": "Refund amount cannot exceed original transaction amount"
}

​
404 Not Found

{
  "statusCode": 404,
  "success": false,
  "message": "Original transaction not found"
}

​
409 Conflict

{
  "statusCode": 409,
  "success": false,
  "message": "Transaction has already been fully refunded"
}