Skip to main content

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.

tip

For a comprehensive reference on the available parameters, please see our API Reference.

Sample request & response​

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"
    }
  }
}

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.

tip

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.

info

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.

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"
    }
  }
}

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.