Handling Payment Issues
By this point, you’ve successfully implemented the Checkout to enroll your customers, great! And you’ve also started to collect payments, even better!
But it’s important to remember that transactions can fail for many reasons, so it’s crucial to have a robust payment recovery system in place in order to capture lost payments. This will help merchants maximise revenues, shorten the bill-to-cash cycle and optimise cash management.
SlimPay’s API and remittance file management system offer numerous means for detecting failed payments, notifying merchants of R-transactions as well as mechanisms for recovering payments that have been lost.
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.
Simulating payment issues
If a payment fails in your live production environment, a payment issue will be created by SlimPay with the information provided by the clearing house or bank.
To prepare and test your payment recovery implementation, SlimPay offers a mechanism for creating simulated failed payments in its preprod environment.
To do this, you must sign a SEPA mandate, filling in the familyName
property of the signatory object with a specific SEPA error code. The table below outlines the required format and a number of payment issue examples:
Payment Scheme | Format | Example |
---|---|---|
SEPA | ISSUE-SEPA-REJ-CODE | ISSUE-SEPA-REJ-AM04 for "Insufficient funds". |
SEPA | ISSUE-SEPA-REJ-CODE | ISSUE-SEPA-REJ-AC04 for "Account closed". |
SEPA | ISSUE-SEPA-REJ-CODE | ISSUE-SEPA-REJ-AC06 for "Account blocked". |
Below is an example of this mandate signature API call using our using our PHP HTTP Client:
'items' => [
[
'type' => ''signMandate',
'action' => 'sign',
'mandate => [
'reference' => null,
'signatory' => [
'honorificPrefix' => 'Mr',
'givenName' => 'John',
'familyName' => 'ISSUE-SEPA-REJ-AM04',
'email' => 'change.me@slimpay.com',
'telephone' => '+33612345678',
'companyName' => null,
'organizationName' => null,
'billingAddress' => [
'street1' => '27 rue des fleurs',
'street2' => 'Bat 2',
'city' => 'Paris',
'postalCode' => '75008',
'country' => 'FR'
]
]
]
]
]
Now, SlimPay will automatically reject any payment created using this mandate, and a payment issue will be created.
Please note: simulating card payment issues using special values is not yet supported. You can submit a request and we will create some card payment issues for your tests.
It's also important to note these simulation SEPA error codes were designed to test one-off direct debit payments only. They cannot be used to simulate errors for recurrent direct debit plans.
The example code below creates 14 payments to simulate how to react when payment issues occur:
$rel = new Hal\CustomRel('https://api.slimpay.net/alps#create-payins');
$follow = new Http\Follow($rel, 'POST', null, new Http\JsonBody(
[
'scheme' => 'SEPA.DIRECT_DEBIT.CORE',
'amount' => 29.99,
'creditor' => [
'reference' => 'yourCreditorReference'
],
'mandate' => [
'reference' => 'theMandateReferenceFromStepOne'
]
]
));
for ($i = 1; $i <= 14; $i++) {
$payment = $hapiClient->sendFollow($follow);
echo "<p>$i. Payment " . $payment->getState()['id'] . ' created.</p>';
}
Managing payment issues by API
The process of managing failed payments by API begins with notification; in order words, by retrieving any payment issues created by SlimPay. This can be done using the search-payment-issues relation available at the entry point. To do this, you will need to provide the following parameters:
creditorReference
: your creditor referencescheme
: the payment scheme you used when you created the payments (searches for direct debits or card payments must be done using a separate API call for each scheme)executionStatus
: set this value totoprocess
and/ortoreplay
Below is an example of the search-payment-issues call:
$follow = new Http\Follow(new Hal\CustomRel('https://api.slimpay.net/alps#search-payment-issues'), 'GET', [
'creditorReference' => 'yourCreditorReference',
'scheme' => 'SEPA.DIRECT_DEBIT.CORE',
'executionStatus' => 'toprocess'
]);
$collection = $hapiClient->sendFollow($follow);
The server will respond with one or more failed payments in a collection called paymentIssues
. By following the get-payment link attached to each payment issue, you can retrieve more details of the original payment that failed.
$follow = new Http\Follow(new Hal\CustomRel('https://api.slimpay.net/alps#get-payment'));
$initialPayment = $hapiClient->sendFollow($follow, $issue);
$initialPaymentState = $initialPayment->getState();
At this stage, it’s important to understand SlimPay’s automatic retry feature. In the event of a failed payment, a new attempt can be made to collect the funds. SlimPay will automatically attempt to process the failed payment again, notifying your customer of this via a customisable SMS or email. Contact our Customer Success team to find out how automatic retry can be configured for your business.
Now, concerning the failed payments returned by the SlimPay server; if automatic retry is not configured, simply acknowledge the failed payment by following the ack-payment-issue relation in the links attached to the failed payment, which sets the executionStatus to processed.
$follow = new Http\Follow(new Hal\CustomRel('https://api.slimpay.net/alps#ack-payment-issue'), 'POST');
$hapiClient->sendFollow($follow, $issue);
At this point, no further action will be taken with the failed payment. To recover the lost revenue, refer to the documentation regarding payment recovery below.
If automatic retry is configured, you need to keep an eye out for a relation called get-replayed-payment in the links returned in the get-payment call. If the payment has a get-replayed-payment link, this means that the failed payment has already been automatically retried by SlimPay. You simply need to acknowledge the payment issue using the method explained above and wait to see if the payment retry is successful.
If the payment issue does not have a get-replayed-payment link (despite being configured for automatic retry), there will no longer be any future automatic retries of the failed payment. At this point, you must acknowledge the failed payment using the method explained above, and recover the lost revenue using the payment recovery mechanisms described below.
Managing payment issues by File
Merchants can alternatively choose to be notified of failed payments by file. A complete list of all failed payments can be generated daily in a REJ file, deposited by SFTP or accessible via the Dashboard.
Please note: A merchant must choose to manage and be notified of payment issues either by API or by file, but not both. Our Customer Success team will be happy to advise you on which is the best structure suited to your business needs.
Recovering failed payments
After being notified of a failed payment (either by API or by file), SlimPay offers a range of mechanisms to recover the potential lost revenue.
If a merchant already has an existing and active card alias for the debtor in question, they can initiate a server-to-server card payment to recover the lost revenue. Merchants should inform their customers that a direct debit payment has failed and it is being collected by alternative means. Additionally, customers should be given specific instructions on the actions needed in order to prevent any failed payments in the future. Documentation on creating direct card payments can be found here.
Another available method of failed payment recovery is card by link, where merchants can email debtors a link that will redirect them to the SlimPay Checkout in order to submit a card payment. Once again, the email should explain to the debtor that a direct debit payment has failed as well as the specific actions needed in order to prevent any failed payments in the future. Documentation regarding SlimPay’s card by link facility can be found here.
Finally, a merchant has the option to create a payment recovery portal that can be integrated into their own application or website. An email will direct the debtor to the merchant’s website or application, where they can login to a dedicated client space. Here, they can nominate to pay their outstanding direct debit by card, and will be redirected to the SlimPay Checkout. While this option requires more technical development by the merchant, the payment recovery portal offers a rich, purpose-built solution which can be fully customised to reflect the branding of a merchant and enhance the payment recovery journey of a debtor.
Please note: It’s important to note that for the recovery portal use case, merchants should not acknowledge failed payments before a debtor has paid them. All outstanding payment issues must remain unacknowledged (and therefore in a toprocess state) in order to appear in a debtor’s client space. Once the customer has paid their outstanding payments, these can then be acknowledged in order to remove them from their client space.