Quick Start Guide

While most of the code relates to API usage errors, there are a few that are critical to users' experience.

Improve your users' experience with a few simple tasks.

Keep your customers informed

Whenever a <customer-message> is included in the PAYMENT_REQUEST response, display its value in the frontend.


Customer messages are available in Dutch, English, French and German.

The language of <customer-message> depends on the data from the PAYMENT_REQUEST: customer-language (if submitted), shop-language (if submitted) or the country code of the billing address.


<customer-message> can contain html-hyperlinks (Standard format: &lt;a href="http.."&gt;...&lt;/a&gt;).

Please make sure that these links are displayed correctly.

If <customer-message> is not included, there is most likely an error in the use of the API. Check the <reason-code> for more details. Display your own generic error message to customers.

Transaction accepted

A successfully processed PAYMENT_REQUEST is answered with reason code 700.

If you have not already done so, save the transaction in your system, submit your order ID within a PAYMENT_CONFIRMATION request to Ratepay and forward your customers to the next page.

700: Request successful

Typos, mistakes, failures

In case of result code 150 it could be possible to complete the purchase order with a new transaction.

Your customers should be able to validate and correct the data they provided.


We recommend to limit the number of order attempts to 3 per 24 hours.


If the amount of result code 150 is quite high, check the <reason-code> to rule out technical errors on your part.

150: Processing failed

Transaction declined

In case we reject your PAYMENT_REQUEST you will get result code 401.


Legally you have to display the value of <customer-message> in the frontend.

Your customers should be able to select a different payment method, like Credit Card or Prepayment, or it should be possible for the customer to correct their data, depending on the responded Reason Code.


We recommend to hide Ratepay's payment methods for 24 hours.

401: Transaction result error

Monitor reason codes

Log the reason codes to identify possible technical errors and constantly improve your users' experience.