Refund Payments
Processing refunds is a part of any business, so it’s important to know how you can return funds to your customer when the need arises. SlimPay allows merchants to reimburse direct debit and card payments using our API, through batch file injection or by using the Dashboard. Payments can be refunded partially or in full.
Please note
This guide does not cover the basics of API authentication or the format of requests and responses. Please review these sections if you are unfamiliar with these concepts.
All of the code examples in our guides are written in PHP and are based on our HAPI Client, developed by SlimPay to reduce the code complexity of interfacing with our API. Please refer to our HTTP client page for more details on using these libraries.
Refunding a SEPA direct debit by API
In order to refund a direct debit, a number of conditions must be satisfied:
- The recipient must have been debited by SlimPay in the past
- The recipient must have an active SEPA mandate
- The refund amount must be less than or equal to the merchant's available funds
- The refund amount must be less than or equal to the total amount debited from the recipient's account over the past 14 months (minus the already refunded amount)
An SDD refund is initiated by creating a SEPA credit transfer using the create-payouts relation, which can be found at the API entry point.
The table below lists all of the parameters that you need to create a refund. Be sure to include all the properties that are mandatory, as well as any optional ones you wish. All of the data you provide must conform to the constraints outlined in our API reference.
Parameter | Mandatory | Format | Max length |
---|---|---|---|
creditor » reference | Alphanumeric | 35 | |
mandate » reference or subscriber » reference |
Alphanumeric | 35 | |
payment reference If null , SlimPay will generate a unique reference. |
Alphanumeric | 35 | |
amount | Decimal | 19 | |
currency
|
An ISO 4217 currency code | 3 | |
scheme
|
Alphanumeric | 35 | |
label | Alphanumeric | 140 | |
executionDate As soon as possible if null . |
A date, formatted to ISO 8601 standard E.g. 2021-11-03T00:00:00.000+0100 | 28 |
Below is an example of the create-payouts API call using our PHP HTTP Client:
$rel = new Hal\CustomRel('https://api.slimpay.net/alps#create-payouts');
$follow = new Http\Follow($rel, 'POST', null, new Http\JsonBody(
[
'creditor' => [
'reference' => 'yourCreditorReference'
],
'mandate' => [
'reference' => 'theMandateReference'
],
'amount' => 199.99,
'currency' => 'EUR',
'scheme' => 'SEPA.CREDIT_TRANSFER',
'label' => ''Refund label',
'executionDate' => null
]
));
$payment = $hapiClient->sendFollow($follow);
In the example above, the mandate reference was used to refund the direct debit payment. You could also provide the subscriber reference instead, and SlimPay will refund the most recently active mandate associated with this subscriber.
Please note: a direct debit can be subject to a dispute from the debtor's bank for up to 13 months. Because the credit transfer method outlined above is in no way connected to the original direct debit, the debtor could potentially receive the amount twice. So be very careful when using this method of refunding payments.
Refunding a card payment
Refunding a card transaction (partially or in full) involves a slightly different process. We must first fetch the original card payment we want to reimburse using the search-payment-by-id relation available at the API entry point, providing the payment ID as a parameter.
Alternatively, you can find the payment using the search-payments relation available at the API entry point, providing your creditor reference, the payment scheme (CARD) and the subscriber reference as parameters. In either case, the card payment can then be refunded by following the refund-payment relation which is returned by the server in the resource links:
$rel = new Hal\CustomRel('https://api.slimpay.net/alps#search-payment-by-id');
$follow = new Http\Follow($rel, 'GET', [ 'id' => 'thePaymentId' ]);
$payment = $hapiClient->sendFollow($follow);
$rel = new Hal\CustomRel('https://api.slimpay.net/alps#refund-payment');
$follow = new Http\Follow($rel, 'POST', null, new Http\JsonBody(
[
'reference' => 'The refund payment reference',
'amount' => 29.99
]
));
$payment = $hapiClient->sendFollow($follow, $payment);
The refund reference and amount parameters are optional. A partial amount of the original payment can be specified. If not provided, the full amount will be refunded.
Parameter | Mandatory | Format | Max length |
---|---|---|---|
reference If null , SlimPay will generate a unique reference. |
Alphanumeric | 35 | |
amount If null , the full amount of the original payment will be refunded. |
Decimal | 19 |
Please note: A card refund will be successful even if a debtor’s card has expired or has been stolen. Under those circumstances, the funds will be paid into the customer’s bank account. The only instance where a card refund might fail is if the customer's bank account no longer exists.
Please be aware that card payments can be subject to disputes and chargebacks. It's important to ensure a payment has not already been disputed before employing the refund-payment process described above.
Refund payments by file
Direct debit payments can also be reimbursed by batch file, meaning you can inject a remittance file for processing dozens, hundreds or even thousands of refunds in a single operation. Card payments cannot be refunded by file. Documentation regarding refunds by batch file can be found here.
Refund payments by Dashboard
Refunds can also be processed using SlimPay’s Dashboard interface. For documentation on this process, please refer to our Help Center.
Determining whether a payment refund was successful
SlimPay allows merchants to track the status of refunded payments to confirm whether they have been successfully processed.
To retrieve direct debit refunds, you can use the search-payments relation available at the API entry point, providing your creditor reference and the payment scheme (SEPA.CREDIT_TRANSFER) as parameters. All SDD refunds will be returned in a collection by the SlimPay server.
Card refund operations are synchronous, meaning the status of the transaction will be returned by the SlimPay server when it is created. However, the search-payments relation can also be used to retrieve card refunds, by providing your creditor reference, the payment scheme (CARD) and direction OUT as parameters. All card refunds will be returned in a collection by the SlimPay server.
Because card refunds are explicitly connected to an original payment, they can also be retrieved using the search-payment-by-id relation available at the API entry point, providing the ID of the original card payment. In the links property of the payments returned by the SlimPay server, you can follow the get-refunds relation to retrieve the card refund associated with this payment.
Card refunds are generally processed within 48 hours. Direct debit refunds (credit transfers) are generally processed the day following the execution date (assuming the payment was submitted before the cut-off threshold of 3am UTC).