Process Refunds
Before you start
To interact with our Payment APIs you must obtain an access token using the API credentials provided to you during your onboarding process. You will have at least one set of credentials per environment (Sandbox and Live). More details can be found in our Getting Started guide.
Initiate a Full Refund
By requesting a full refund, our system will return the full amount of a payment to the buyer. The refunded amount will be deducted from all the involved actors' accounts - depending on the configured routing at the payment initiation - and automatically transferred to the buyer.
In order to initiate a full refund, it is required to provide the related payment identifier, a description (it would be displayed at the bank statement). Optionally, a reference and a webhoook URL can be also provided.
For a comprehensive reference on the available parameters, please see our API Reference.
Sample request & response
- Sandbox
- Live
POST https://api.sandbox.getpaid.io/refunds
Sample request
curl -X POST \
https://api.sandbox.getpaid.io/refunds \
-H 'authorization: Bearer {{your_access_token}}' \
-H 'content-type: application/json' \
-d '{
"payment_id": "pay_926ap9a2ioesd1p0qsfjuk1bvv",
"description": "Refund for ORD-123456",
"reference": "REFUND-123456",
"urls": {
"webhook": "https://webhooks.haircutz.co/getpaid"
}
}'
Sample response
{
"id": "rfd_473cr1y0ghbyc3m1yfbwvn3nxx",
"status": "initiated",
"_links": {
"self": {
"href": "https://api.getpaid.io/refunds/rfd_473cr1y0ghbyc3m1yfbwvn3nxx"
}
}
}
POST https://api.getpaid.io/refunds
Sample request
curl -X POST \
https://api.getpaid.io/refunds \
-H 'authorization: Bearer {{your_access_token}}' \
-H 'content-type: application/json' \
-d '{
"payment_id": "pay_926ap9a2ioesd1p0qsfjuk1bvv",
"description": "Refund for ORD-123456",
"reference": "REFUND-123456",
"urls": {
"webhook": "https://webhooks.haircutz.co/getpaid"
}
}'
Sample response
{
"id": "rfd_473cr1y0ghbyc3m1yfbwvn3nxx",
"status": "initiated",
"_links": {
"self": {
"href": "https://api.getpaid.io/refunds/rfd_473cr1y0ghbyc3m1yfbwvn3nxx"
}
}
}
Initiate a Partial Refund
By requesting a partial refund, our system will return just a specific sub-amount of a payment to the buyer. The refunded amount will be deducted from all the involved actors' accounts - depending on the configured routing at the payment initiation - and automatically transferred to the buyer.
There are no restrictions on the number of partial refunds that can be requested for a payment. However, there are some important keypoints to take into consideration when requesting partial refunds:
- The sum of all the partial refunds cannot exceed the original payment amount.
- It is not possible to refund from an actor more amount than the one that was originally routed.
In order to initiate a partial refund, it is required to provide the related payment identifier, a description (it would
be displayed at the bank statement), and a routing
object. Optionally, a reference and a webhoook URL can be also
provided.
Please note that we don't support partial refunds for payments whose payout hasn't been started yet.
For a comprehensive reference on the available parameters, please see our API Reference.
Routing a refund
At the partial refund initiation, it is possible to specify the source of the funds to be refunded.
This is done by providing a routing
object, which allows to specify the amount to be refunded from the platform or merchants involved in the payment.
The routing
object is composed of two properties:
platform
: Contains the amount to be refunded from the platform.merchants
: A list of merchant routes. Every route contains the amount to be refunded from the merchant and the related account identifier.
The amounts specified in the refund routing cannot exceed the original amounts configured at the payment routing. It is possible to check the refundable amount from every actor by calling the Get Payment endpoint.
Sample request & response
Let's suppose that we have a captured
payment that has the following routing configuration:
{
"platform": {
"amount": 100
},
"merchants": [
{
"account_id": "acc_4zjjxn0nm1tnweqbttedkvnsc8", // Seller
"amount": 2500,
"refundable_amount": 2500,
...
},
{
"account_id": "acc_4djj3n0hm1tn2eqwetedkvnsc3", // Supplier
"amount": 500,
"refundable_amount": 500,
...
}
]
}
The total amount of the payment above is 31.00 EUR:
- 1.00 EUR routed to the platform.
- 25.00 EUR routed to the seller.
- 5.00 EUR routed to the supplier.
Since no partial refunds have been executed yet, the refundable amounts are equal to the original amounts.
In the following example, we will request a partial refund 15.00 EUR to the buyer. In this case, the funds will be taken from the seller's (10.00 EUR) and the supplier's (5.00 EUR) routed amounts.
On every refund request, the refunds engine will validate if the involved actors have enough routed funds available for refunding. If it does not, the request will be rejected.
- Sandbox
- Live
POST https://api.sandbox.getpaid.io/refunds
Sample request
curl -X POST \
https://api.sandbox.getpaid.io/refunds \
-H 'authorization: Bearer {{your_access_token}}' \
-H 'content-type: application/json' \
-d '{
"payment_id": "pay_926ap9a2ioesd1p0qsfjuk1bvv",
"description": "Refund for ORD-123456",
"routing": {
"merchants": [
{
"id": "acc_4zjjxn0nm1tnweqbttedkvnsc8", // Seller
"amount": 1000
},
{
"id": "acc_4djj3n0hm1tn2eqwetedkvnsc3", // Supplier
"amount": 500
}
]
},
"reference": "REFUND-123456",
"urls": {
"webhook": "https://webhooks.haircutz.co/getpaid"
}
}'
Sample response
{
"id": "rfd_473cr1y0ghbyc3m1yfbwvn3nxx",
"status": "initiated",
"_links": {
"self": {
"href": "https://api.getpaid.io/refunds/rfd_473cr1y0ghbyc3m1yfbwvn3nxx"
}
}
}
POST https://api.getpaid.io/refunds
Sample request
curl -X POST \
https://api.getpaid.io/refunds \
-H 'authorization: Bearer {{your_access_token}}' \
-H 'content-type: application/json' \
-d '{
"payment_id": "pay_926ap9a2ioesd1p0qsfjuk1bvv",
"description": "Refund for ORD-123456",
"routing": {
"merchants": [
{
"id": "acc_4zjjxn0nm1tnweqbttedkvnsc8", // Seller
"amount": 1000
},
{
"id": "acc_4djj3n0hm1tn2eqwetedkvnsc3", // Supplier
"amount": 500
}
]
},
"reference": "REFUND-123456",
"urls": {
"webhook": "https://webhooks.haircutz.co/getpaid"
}
}'
Sample response
{
"id": "rfd_473cr1y0ghbyc3m1yfbwvn3nxx",
"status": "initiated",
"_links": {
"self": {
"href": "https://api.getpaid.io/refunds/rfd_473cr1y0ghbyc3m1yfbwvn3nxx"
}
}
}
Once the partial refund is requested, the refundable_amount
fields (within the payment routing) will suffer a deduction of the refunded amount. The payment routing will be updated as follows:
{
"platform": {
"amount": 100,
"refundable_amount": 100,
},
"merchants": [
{
"account_id": "acc_4zjjxn0nm1tnweqbttedkvnsc8", // Seller
"amount": 2500,
"refundable_amount": 1500,
...
},
{
"account_id": "acc_4djj3n0hm1tn2eqwetedkvnsc3", // Supplier
"amount": 500,
"refundable_amount": 0,
...
}
]
}
Then, after this 15.00 EUR partial refund, the platform has still 1.00 EUR available for refunding, the seller has 15.00 EUR available, and the supplier has no routed funds available for refunding.