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
andrefundTo
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
andrefundTo
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.
Última actualización