Refund a payment session

This page will help you complete a refund for a completed payment session.

1. Requirements

We assume you already have a console account up and running, and you already have generated a payment session that has been completed. You can only refund a payment session that has been completed (authorized and paid successfully), we support full and partial refunds against a single payment.

The refund amount cannot be greater than the amount paid initially.

2. General flow

The refund is essentially the same process as a payment session, we first need to have the details of the customer account which depending of the bank will be either shared with us in the initial payment session or we will need to ask for it to the customer (see diagram below). Once we have the customer bank details, we just need the consent from the merchant to send the money to the customer's account.

📘

Refund states

You can find refund states here.

3. Generating a refund through the API

a. Initiate the refund
The following cURL command creates a Refund for an existing payment session. Remember to Replace YOUR_API_KEY with your test key, YOUR_API_SECRET with your test secret and base 64 encode the result; and replace PAYMENT_ID with a completed payment session.

curl --location --request POST "https://api.banked.com/v2/refunds" \
  --header "Content-Type: application/json" \
  --header "Authorization: Basic base64(YOUR_API_KEY:YOUR_API_SECRET)" \
  --data "{
    \"success_url\": \"http://example.com/success?id=__PAYMENT_ID__\",
    \"error_url\": \"http://example.com/error\",
    \"amount\": 400,
    \"reference\": \"refund Candles\",
    \"payment_session_id\": \"PAYMENT_ID\"
}"

📘

Adding payee information

Optionally, you may also include the destination account information for the refund in the payee object (see API docs). This will only be used if this is not available from the original payment, and will be ignored otherwise.

After running this in your terminal, you'll see the response object.

{
    "amount": 400,
    "amount_formatted": "£4.00",
    "payment_session_id": "PAYMENT_ID",
    "refund_payment_session_id": null,
    "state": "awaiting_details",
    "url": "http://payments.banked.com/refunds/0e61cc47-6b92-4a6a-8951-3ddd8a462ee8"
}

b. Make sure Banked knows where to refund the money
Depending on the original payment provider, Banked may or may not know the bank details of where to refund the payment.
If we do not know the details, you will see the state awaiting_details in the response. In this case, we will email the user a form asking for their details - the form can also be found in the url property.
Once the user has provided their details, the status will change to awaiting_payment.

c. Get the refund payment session ID
Now that the refund is in the awaiting_payment state, Banked has created a refund session. You can retrieve it by calling the following GET request:

curl --request GET 'https://api.banked.com/v2/payment_sessions/<PAYMENT_ID>' \
--header 'Authorization: <AUTHORIZATION>'

In the response, you will find a refunds object, with the refund_payment_session_id:

"refunds": [
        {
            "amount": 4000,
            "amount_formatted": "£40.00",
            "payment_session_id": "e8773200-d4a6-4468-8f8a-1a6473692255",
            "refund_payment_session_id": "8373a8b4-b3af-49de-8699-a7d0f2c468dd",
            "state": "awaiting_payment"
        }
    ],

d. Authorise the refund
Finally, you need to authorise the refund session, instructing Banked to move the funds from your account into your customer's account.
View the refund session details the same way as you would a normal payment session (use the refund_payment_session_id you got from the previous step!).

curl --request GET 'https://api.banked.com/v2/payment_sessions/<REFUND_PAYMENT_SESSION_ID>' \
--header 'Authorization: <AUTHORIZATION>'

On the response, you will see a url property - this is the authorisation URL you need to complete for Banked to be able to move the funds from you to the user.

{
    ...
    "reference": "bnkdzOo2iegk",
    "sent_at": "2021-04-19 10:35:25 UTC",
    "state": "awaiting_provider",
    "url": "https://checkout.banked.com/8373a8b4-b3af-49de-8699-a7d0f2c468dd?v3"
}

e. That's it!
Banked will now action the refund. You can check that the refund status has moved from awaiting_provider to sent.

4. Generating a refund through the console

You can also create refunds inside your console, go the payment session you want to refund. At the bottom of the page you'll find a refund button with an amount. (note that you can set an amount equal or lower than the full amount).

Once you clicked the refund button, if we have don't have the details of the end customer we'll send an email to the end customer with a link to fill their account details, you can see in the status in the console and you also have the link that was sent to the end customer.


Did this page help you?