This page describes how to use the Banked API to refund a previously completed payment session.
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.
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 on the bank, will be either shared with us in the initial payment session, or we will need to ask for it from the customer. Once we have the customer's bank details, we just need the consent from the merchant to send the money to the customer's account.
Generating a refund through the API
1. Initiate the refund
The following cURL command creates a Refund for an existing payment session. Remember to use your base 64 encoded test key and test secret value in the Authorization header, 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. 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"
}
2. 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.
3. 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"
}
]
4. 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"
}
Banked will now action the refund. You can check that the refund status has moved from awaiting_provider to sent.
Generating a refund through the console
You can also create refunds inside your console. Locate the payment session you want to refund in the console. At the bottom of the page, you'll find a refund button with an amount.
You can set any refund amount equal or lower than the full amount.
Once you click 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. 