API FAQ


Can I disable Second Chance through API?

Yes, it is possible to disable Second Chance through the dedicated API. This can be done in the transaction request when you create an order, by using the value false instead of true.

Does MultiSafepay still offer the XML API?

The XML API is deprecated and succeeded by the JSON API. The XML endpoint can still be used to process transaction requests. However, new payment methods, features and tools will only be supported by using the JSON API.

There are no plans to phase out the XML integration at this point, but this might change in the foreseeable future.

Generate your API key

An API key is required to successfully establish a connection between your website and the MultiSafepay services.

Currently an API key can only be requested when a website URL is inputted into the backend of the MultiSafepay interface. Thus, an API key will only be generated as long as the field contains the URL of your website. Only then will it be possible to process data and payments.

It is not possible to generate an API key in any other way e.g. ERP systems. An export of all transactions via SFTP can be made with the Accountant Export to serve your bookkeeping needs. An automatic Accountant Export can also be requested to MultiSafepay and sent daily, weekly or monthly.

Google Analytics tracking through API

It is possible to track the behavior of your customers through Google Universal Analytics tracking. However, this is restricted only to direct orders. If a customer reaches the MultiSafepay payment page, the UA-code will be loaded and you will be able to see that in the corresponding HTML.

For redirected orders (e.g. iDEAL redirect, some cases of Klarna, Afterpay, etc.), there is NO tracking available, as customers will not pass through a MultiSafepay page after checkout and before the successful payment page.

We are currently working on updating the documentation on Google Analytics to accommodate as many of your possible querries as possible. Please check again soon!

How does the notification URL work?

Notification

Our API will notify your web server when the status of a transaction changes.
We will add 2 parameters to the notification:

  • Transactionid
  • Timestamp.

MultiSafepay will always call the notification_url with the timestamp parameter.

When MultiSafepay calls the notification_url without a timestamp, the call should be ignored.
The call should also be ignored when the same order status is received.

Example

In a request we receive:
This request is done through a GET request.

"order_id": 12345,  
"notification_url": https://yourdomain.com/index/paymentprovidernotification?invoice_id=840,

When the status of this transaction changes, we will notify the web server with this URL: https://yourdomain.com/index/paymentprovidernotification?invoice_id=840&transactionid=12345&timestamp=140292929

Carry out the following 3 tasks within your custom implementation:

  1. Perform a status request on the order using the transactionid provided
  2. Update the status of the order within your own systems
  3. Return an OK message. We expect an empty page with just OK in the body of the response on this request, with a HTTP 200 OK in the header.

Note:

  1. Always use (http or https) in the URL
  2. A notification URL supplied in your MultiSafepay Control will be leading. This means that we will use the provided notification URL available in your MultiSafepay Control first
  3. Port numbers should not be included in the notification URL. Our platform only processes standard ports due to security reasons.

Response

As response, MultiSafepay expects an empty page with just OK in the body of the response on this request, with a HTTP 200 OK in the header. When an OK is not received, MultiSafepay will repeat this notification. The notification with timestamp is repeated twice within 15 minutes.

Please make sure that our IP ranges is authorized to process the notification URL.

When our systems call the code at your notification_url, your code can perform a GET request on our API to receive the actual status of the transaction. The field status is relevant for further processing of the order.

What does Locale do?

A locale is a set of parameters that defines the user’s language, region and any special variant preferences that the user wants to see in their user interface. Usually a locale identifier consists of at least a language code and a country/region code (e.g. en_US). A locale can be included to provide localized payment pages for the customer. Use the format ab_CD with ISO 639 language codes and ISO 3166 country codes. This will show the desired language for that customer (if supported by MultiSafepay) on both the payment page and the emails MultiSafepay sends. When left empty or with a unsupported value, en_US, meaning American English, is used.

In some cases, the locale is also used to show certain variants of payment methods, such as:

The locale is also important for sending the correct email template to the customer. For example, if an email template is set for the German customer, but the locale is received as en_US, the email template will be sent in English and not in German.

What type of personal transaction details are required to be sent via the MultiSafepay API?

As online payment provider, MultiSafepay is obliged by law to monitor transactions and it’s clients. As a result, it must be clear to MultiSafepay what type of service or products are purchased per transaction and by whom.

Please help us in our duty by sending:

  • the exact product details
  • client name
  • customer IP-address
  • country
  • email address

for all orders automatically. Failure of sending the required information may result in extra screening steps from MultiSafepay and/or a request for copies of invoices of specific orders.

Why request the IP address of the customer?

ip_address

Post-payment and credit card payment methods require the customer ip_address to be validated and thus, we need the actual IP address of the end user within the ip_address field. This means that the optional parameter “ip_address (optional) within the JSON request is now a “required” field when processing post-payment and/or credit card transactions.

Please note! When validating the localhost ip_address instead of the end user’s ip_address, it may result in transactions being marked with the status uncleared or even be rejected/declined.

   "customer": {
        "ip_address": "31.148.195.10",
        "forwarded_ip": "" 

forwarded_ip

The X-FORWARDED-FOR header of the customer request when using a proxy.

forwarded_ip is to be used when there is a proxy. In all other cases they need to use the ip_address to retrieve the IP address of the customer.

Uncleared status or Declined

Due to the validation on the IP address of the end user (customer) a transaction can unnecessarily be marked with the status uncleared or even be declined.

Before a payment is accepted, a fraud check will take place on the transaction. The required ip_address field is one of the checks processed in the validation of the payment. When provided with an empty or incorrect IP address (by providing the ip_address of the webshop instead of the customer), the chances that the transaction will be marked with the status uncleared are very high.

Credit cards and post-payment methods represent a high risk for fraud. Therefore, the validation of each transaction will automatically take place to protect the merchants processing with MultiSafepay.

Other languages

Liever uitleg in het Nederlands? Neem contact op met uw accountmanager.

Vuoi ricevere informazioni in italiano? Contatta il tuo account manager.

Prefieres tener la explicación en Español? Contacta con tu gerente de cuentas.

Vous préférez une explication en français? Contactez votre gestionnaire de compte.