v1.1 - Granular reason codes and adjusted customer messages

Introduction

In case of a buyer’s non-technical declines, we now offer you more transparency. For you, the increased granularity of decline reason code responses from Ratepay's payments API provides actionable information to build business logic to handle any error. Unlike the current reason code responses, the new version will enable you to convert more order attempts by implementing smart recovery logic, boost your sales and improve buyer satisfaction. The increased granularity of response codes will also improve your ability to analyze declines.

What is going to change?

New API reason codes for PAYMENT_REQUEST operations

The response result of a PAYMENT_REQUEST operation can contain one of the following three new reason codes:

• 720: Declined - Payment attribute
• 721: Declined - Transaction risk
• 730: Declined - Buyer identity

The new reason codes split off from the existing reason code 703: Request not successful by giving a more detailed description of why a request was rejected. Transactions that previously would have received 703 as reason code, can now receive one of the following reason codes: 703, 720, 721, 730.

For further details about the individual reason codes please visit the corresponding reason code page.

Changes to existing customer messages

In an effort to improve the customer experience for rejections we are rewording the customer message for 703: Request not successful.

Why are we making these changes?

We want to give our partners the option to use recovery strategies for rejected requests where applicable, leading to increased conversion rates. In addition, we wanted to increase the transparency towards our partners by sharing with them more details about how our API makes decisions.

For merchants

The increased granularity of decline reason codes responses from the Ratepay API provides actionable information for merchants to build and extend business logic, enabling them to convert more order attempts by implementing smart recovery logic. Furthermore, the new reason codes might provide merchants with insights about their customers.

For consumers

The implemented rewording of customer messages is intended to reduce consumer frustration when a request is rejected. Additionally, some customer rejections can be converted into a successfully completed checkout.

Who is going to be affected?

Everyone with a direct connection to the Ratepay Payment API will be receiving the new reason codes and the updated customer messages.

Which API Version does this apply to?

This change impacts all our Payment API versions.

Which integration types are affected?

If you are a seller, merchant, marketplace, payment service provider or software developer and evaluating Ratepay's responses, you should check how the changes may affect your environment, checkout and reports.

If you are connected via a Payment Service Provider (PSP), your PSP might forward you the changes. You can coordinate with your PSP how exactly these changes affect you, as well as how you can take advantage of them.

If you are connected via one of Ratepay's shop plug-ins (e.g. for Shopware, Magento, OXID) you automatically benefit from the improvement.

What might be affected?

Following is a non-comprehensive list of merchant-side components that might be affected by the changes. The list is by no means comprehensive, but intended to provide context and minimal suggestions for evaluation.

Website checkout

The following functionality or elements in your checkout might be affected:

• customer message - if you are validating the customer message sent with the response result of a PAYMENT_REQUEST
• blending out of Ratepay as a payment method - in case you have implemented retry logic

Monitoring of checkout

In case you are monitoring for select reason codes (e.g. 703: Request not successful), you should expand the list of reason codes.

Reporting of checkout statistics

If you are reporting and analysing the acceptance rate of the Ratepay API via 703: Request not successful, future reports will be affected.

When will the change happen?

The changes will be rolled out in two stages:

18 May 2020 - Deployment to integration environment

The changes will be deployed to our integration environment. That means that requests sent with the pre-specified test cases will return the new reason codes and customer messages.

You can find more information on how to trigger specific responses in our integration environment here.

15 June 2020 - Deployment to production environment

The changes will be deployed to our production environment. That means that the response to PAYMENT_REQUESTS could contain the new reason codes and customer messages.

Both changes will be deployed without downtime or a maintenance window.

What do I need to change for the new reason codes?

In case you are evaluating our result and reason codes we recommend making an evaluation of the effects of the changes to your checkout system.

In case you are not validating or analyzing the result and reason codes the changes should not affect you.

We recommend that you evaluate how the changes affect your specific implementation.

What do I need to change for the new customer messages?

In case you are not using the Ratepay-supplied customer message, you will need to add new messages for the new reason codes.

In case you are validating the Ratepay-supplied customer message, you will need to add new messages for the new and changed reason codes.

We recommend that you evaluate how the changes affect your specific implementation.

What will happen if I do not make any changes?

If you have set up monitoring or reporting with specific reason codes, you might encounter errors or anomalous reports. Furthermore, you will not see why some customers were rejected.

If you are validating the customer message, this can lead to errors for the customer in the checkout process.

We recommend that you evaluate how the changes affect your specific implementation.