Refunds

This API provides endpoints for managing refunds related to payments. It includes the ability to create, retrieve, and list refunds.

1. List refunds

[GET] /refunds

This endpoint retrieves a list of refunds based on query parameters. It supports filtering, pagination, and sorting.

Request:

const query = {
  page: number,  // Page number for pagination
  limit: number, // Number of items per page
  query: object  // Optional filter conditions
};

Query Parameters:

• page: The page number for pagination (optional, defaults to 1).

• limit: The number of refunds to retrieve per page (optional, defaults to 10).

• query: A comma-separated list of key-value pairs to filter results. The keys will be the refund fields, and values will be used to match corresponding fields (optional).

Response:

{
  "refunds": [ /* Array of refund objects */ ],
  "page": 1,
  "pageSize": 10,
  "totalPages": 5
}

Refund Object Example:

{
  "_id": "string",
  "paymentIntentId": "string",
  "paymentId": "string",
  "userId": "string",
  "receiverId": "string",
  "refundTo": "string",
  "amount": 100,
  "status": "PROCESSING",
  "createdAt": "timestamp",
  "updatedAt": "timestamp"
}

2. Get Refund by ID

[GET] /refunds/:id

This endpoint retrieves a specific refund by its ID.

Request:

• URL Parameter:

  • id: The ID of the refund to retrieve.

Response:

{
  "_id": "string",
  "paymentIntentId": "string",
  "paymentId": "string",
  "userId": "string",
  "receiverId": "string",
  "refundTo": "string",
  "amount": 100,
  "status": "PROCESSING",
  "createdAt": "timestamp",
  "updatedAt": "timestamp"
}

3. Create Refund

[POST] /refunds

This endpoint creates a new refund for an existing payment.

Request:

{
  "paymentId": "string",// The ID of the payment to refund
  "refundTo": "string"// The address to send the refund to (must be a valid address)
}

Response:

{
  "_id": "string",
  "paymentIntentId": "string",
  "paymentId": "string",
  "userId": "string",
  "receiverId": "string",
  "refundTo": "string",
  "amount": 100,
  "status": "PROCESSING",
  "createdAt": "timestamp",
  "updatedAt": "timestamp"
}

Validation:

• The request must include a valid paymentId and refundTo address.

• The paymentId must correspond to a confirmed payment.

• The refundTo address must be a valid Ethereum address (starts with "0x" and has a length of 42 characters).

• The refund amount must not exceed the available funds in the receiver’s account.

• Refunds cannot be processed if the payment has been withdrawn.

Error Responses:

• 400 Bad Request: Missing required fields or invalid data (e.g., invalid address, insufficient funds).

• 401 Unauthorized: If the user is not authenticated.

• 404 Not Found: If the payment or refund does not exist.

• 500 Internal Server Error: If an unexpected error occurs.

• 500 Internal Server Error: If an unexpected error occurs.

4. Create Partial Refunds

[POST] /refunds/partial

This endpoint creates a new partial refund for an existing payment.

Request:

{
  "paymentId": "string",// The ID of the payment to refund
  "refundTo": "string",// The address to send the refund to (must be a valid address)
  "amount": "number" // The amount to be refunded
}

Response:

{
  "_id": "string",
  "paymentIntentId": "string",
  "paymentId": "string",
  "userId": "string",
  "receiverId": "string",
  "refundTo": "string",
  "amount": 100,
  "status": "PROCESSING",
  "createdAt": "timestamp",
  "updatedAt": "timestamp"
}

Validation:

• The request must include a valid paymentId and refundTo address.

• The paymentId must correspond to a confirmed payment.

• The refundTo address must be a valid Ethereum address (starts with "0x" and has a length of 42 characters).

• The refund amount must not exceed the available funds in the receiver’s account.

• Refunds cannot be processed if the payment has been withdrawn.

Error Responses:

• 400 Bad Request: Missing required fields or invalid data (e.g., invalid address, insufficient funds).

• 401 Unauthorized: If the user is not authenticated.

• 404 Not Found: If the payment or refund does not exist.

• 500 Internal Server Error: If an unexpected error occurs.

• 500 Internal Server Error: If an unexpected error occurs.