Developer Center

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. Therefore, having a robust payment recovery system is crucial for capturing lost payments. This will help merchants maximize revenues, shorten the bill-to-cash cycle, and optimize cash management.

SlimPay’s API and remittance file management system offer numerous means for detecting failed payments, notifying merchants of R-transactions, and mechanisms for recovering lost payments.

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 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.

It's important to note that these simulation SEPA error codes were designed to test one-off direct debit payments only. They cannot be used to simulate errors for recurring 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 "
$i. Payment " . $payment->getState()['id'] . " created.
";
}

Managing Payment Issues by API

The process of managing failed payments by API begins with notification; in other 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 reference
• scheme: the payment scheme you used when you created the payments (searches for direct debits and credit transfers must be done using a separate API call for each scheme)
• executionStatus: set this value to toprocess and/or toreplay

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.

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.

You have the option to create a payment recovery portal that can be integrated into your own application or website. An email or an SMS may also be sent to the debtor. This email can be customised through a support request.

SlimPay's SlimCollect Pay offers a structured method for collecting payments using its innovative Payment Initiated solution. SlimCollect isn't just for collecting the first payment when onboarding customers. It can also help you recover failed payments. To get started, follow the SlimPay documentation for setting up SlimCollect: SlimCollect Setup Guide. The mandate is optional: You can choose if the customer has to sign or not sign the mandate at the end of the journey. The payment will follow the same path as for SlimCollect Pay, meaning that an SCT will be received 1 banking day later on the payment account. The payment recovery via SlimCollect Pay 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.

Additionally, SlimPay offers the Automatic Retry feature. In the event of a failed payment, SlimPay will automatically attempt to process the payment again (if allowed by the scheme), notifying the customer via a customizable SMS or email (optional). This process reduces the administrative burden on the merchant and increases the likelihood of recovering the lost revenue. For more information and to configure automatic retry for your business, please follow our documentation.

By combining these features, merchants can significantly improve their payment recovery processes, ensuring that fewer payments are lost and that revenue is maximized.