API
Welcome to the MultiSafepay API documentation (JSON gateway).
How to navigate the API documentation
The left column contains an overview of our JSON API.
By clicking on a topic, you can find specific information about the specific API request.
The middle column provides the detailed information you are looking for. This contains a description of how to use the API request and a reference for the parameters and types involved.
The right column shows examples of the specific JSON request and response which can be expected.
What our API offers:
Our API enables you to perform different calls through which you can start transactions, update transactions, perform refunds and receive information about transactions.
The API also offers advanced operations to enable you to use split payments and recurring payments.
We encourage you to study this API and start implementing your custom integration against our TEST environment.
For any questions, do not hesitate to contact us at [email protected]
Postman
To make it easier for you to test our API and perform requests, we created a Postman collection. This collection is a group of saved request that allows you to retrieve order information, post payments in our API documentation.
Overview
Environments
TEST API
https://testapi.multisafepay.com/v1/json
LIVE API
https://api.multisafepay.com/v1/json
MultiSafepay provides a TEST environment and a LIVE environment. The TEST environment is useful for developing and testing a new integration with our API as no real transactions are able to be processed. Once the integration has been developed processing real transactions is as simple as addressing the LIVE API and updating the API Key being used.
Authentication
All requests to the MultiSafepay API endpoint require authentication. Authentication is provided by including an API key as an HTTP header in your request. Each website has its own API key so if you are operating multiple websites make sure to use the correct corresponding key for each one of them. The API key can be found under the website settings in MultiSafepay Control.
The HTTP header name for the API Key is: api_key
Localization
GET - /gateways?locale=es
For all requests, MultiSafepay provides an optional localization parameter which is used to specify a language used to display gateway information and other messages in the responses. To get a localized response for any request simply add the ISO 639-1 language code to the query string of any request. The default language is English.
Gateways
A payment gateway facilitates a payment transaction by the transfer of information between the ecommerce webshop, MultiSafepay and the payment method. Available payment methods in your MultiSafepay Control are returned as gateways.
Retrieve all gateways
GET - /gateways?country={country}¤cy={currency}&amount={amount}&include={include}
JSON Response
{
"success": true,
"data": [
{
"id": "MASTERCARD",
"description": "Mastercard"
},
{
"id": "VISA",
"description": "Visa"
},
{
"id": "FASHIONGFT",
"description": "fashiongiftcard",
"type": "coupon"
},
]
}October 2019: There have been reports of faulty functionality of this feature. If you encounter any issues or need assistance on this matter, do not hesitate to contact our Integration team at [email protected]
| Parameter | Type | Description |
|---|---|---|
| country | string | Specify an ISO-3166-1 country code to filter out payment gateways that are not applicable for the specified country. This can be used to simplify the list of payment options presented to the customer by removing payment methods specific to other countries e.g. Giropay or iDEAL. |
| currency | string | Specify an ISO-4217 currency code to filter out payment gateways that are not applicable for the specified currency. This can be used to simplify the list of payment options presented to the customer by only displaying payment methods supported by the transaction currency. e.g. Credit Cards. |
| amount | string | Specify the transaction amount (in cents) to filter out payment gateways that are not applicable for that amount. This is commonly used to exclude Pay After Delivery as a payment option for very small, or large, amounts but can also be configured to exclude other payment methods. |
| include | string | Specify comma delimited additional payment method types. Options: coupons. |
Retrieve a gateway
GET - /gateways/{id}
JSON Response
{
"success": true,
"data": {
"id": "{id}",
"description": "{description of payment method}"
}
}| Parameter | Type | Description |
|---|---|---|
| id | string | The unique identifier of the gateway to be returned. |
Retrieve gateways - Multiple available giftcards
GET - /json/gateways?include=coupons
JSON Response
{
"success": true,
"data": [
{
"id": "MASTERCARD",
"description": "MasterCard"
},
{
"id": "VISA",
"description": "Visa"
},
{
"id": "FASHIONGFT",
"description": "fashiongiftcard",
"type": "coupon"
},
{
"id": "VVVBON",
"description": "vvvbon",
"type": "coupon"
},
{
"id": "FASHIONCHQ",
"description": "fashioncheque",
"type": "coupon"
}
]
}| Parameter | Type | Description |
|---|---|---|
| include | string | Specify comma delimited additional payment method types. |
Adding the coupons value to your GET request will include all your webshop’s available giftcards in the response. See the response example on the side.
Gateway Issuers
GET - /issuers/ideal
JSON Response
{
"success": true,
"data": [
{
"code": "0031",
"description": "ABN AMRO"
},
{
"code": "0751",
"description": "SNS Bank"
},
{
"code": "0721",
"description": "ING"
},
{
"code": "0021",
"description": "Rabobank"
},
{
"code": "0761",
"description": "ASN Bank"
},
{
"code": "0771",
"description": "Regio Bank"
},
{
"code": "0511",
"description": "Triodos Bank"
},
{
"code": "0161",
"description": "Van Lanschot Bankiers"
},
{
"code": "0801",
"description": "Knab"
},
{
"code": "4371",
"description": "Bunq"
},
{
"code": "1234",
"description": "Moneyou"
},
{
"code": "1235",
"description": "Handelsbanken"
}
]
}| Parameter | Type | Description |
|---|---|---|
| id | string | The unique identifier of the payment gateway to retrieve an issuer list for. Currently supported identifiers are: iDEAL |
Direct iDEAL Transactions can have the following Issuers:
| IssuerID | Bank |
|---|---|
| 0031 | ABN AMRO |
| 0761 | ASN Bank |
| 4371 | bunq |
| 1235 | Handelsbanken |
| 0721 | ING |
| 0801 | Knab |
| 1234 | Moneyou |
| 0021 | Rabobank |
| 0771 | Regio Bank |
| 0751 | SNS Bank |
| 0511 | Triodos Bank |
| 0161 | Van Lanschot Bankiers |
Orders
An order needs to be created to process the payment transaction. You have two main types of orders:
- Redirect: Customer will be redirected to MultiSafepay’s payment pages (Connect).
- Direct: Transaction is processed directly.
You can also create a:
- Checkout order: This type creates a “Fast Checkout Order”
- Payment link: A payment link is created and listed in the MultiSafepay Control Panel.
Create an order
POST - /orders
{
"type": "redirect",
"order_id": "my-order-id-1",
"gateway": "",
"currency": "EUR",
"amount": "1000",
"description": "Test Order Description",
"google_analytics": {
"account": "UA-XXXXXXXXX"
},
"payment_options": {
"notification_url": "http://www.example.com/client/notification?type=notification",
"redirect_url": "http://www.example.com/client/notification?type=redirect",
"cancel_url": "http://www.example.com/client/notification?type=cancel",
"close_window": ""
},
"customer": {
"locale": "nl_NL",
"ip_address": "89.20.162.110",
"first_name": "Testperson-nl",
"last_name": "Approved",
"address1": "Kraanspoor",
"house_number": "39C",
"zip_code": "1033SC",
"city": "Amsterdam",
"country": "NL",
"phone": "0208500500",
"email": "[email protected]",
"referrer": "http://test.com",
"user_agent": "Mozilla/5.0 (Windows NT 6.3; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/38.0.2125.111 Safari/537.36"
},
"second_chance": {
"send_email" : true
}
}JSON Response
{
"success": true,
"data": {
"order_id": "My-order-id-1",
"payment_url": "https://payv2.multisafepay.com/connect/99wi0OTuiCaTY2nwEiEOybWpVx8MNwrJ75c/?lang=nl_NL"
}
}Creates redirect order. Default type is “redirect”.
| Parameter | Type | Description |
|---|---|---|
| type | string | Specifies the payment flow for the checkout process. Options: redirect, direct, checkout, paymentlink. |
| gateway | string | The unique gateway id to immediately direct the customer to the payment method. You retrieve these gateways using a gateway request. |
| order_id | string | The unique identifier from your system for the order. |
| currency | string | The currency ISO-4217 you want the customer to pay with. |
| amount | integer | The amount (in cents) that the customer needs to pay. |
| description | string | A text which will be shown with the order in MultiSafepay Control. If the customer’s bank supports it this description will also be shown on the customer’s bank statement. Max. 200 characters. HTML is no longer supported. Use the ‘items’ or ‘shopping_cart’ objects for this. |
| payment_options | object | |
| notification_url | string | Endpoint where we will send the notifications to. notification_url |
| google_analytics | object | Your Google Analytics Site Id. This will be injected into the payment pages so you can trigger custom events and track payment metrics. This parameter is optional. Please check the dedicated Google Analytics FAQ page |
| account | string | Google Analytics Tracking-ID. You can find this in your Google Analytics Dashboard. |
| redirect_url | string | Customer will be redirected to this page after a successful payment. |
| cancel_url | string | Customer will be redirected to this page after a failed payment. |
| customer | object | |
| locale | string | Displays the correct language and payment methods on the Payment page. It also has an influence on sending the set email templates. Use the format ab_CD with ISO 639 language codes and ISO 3166 country codes. Default: en_US. |
| ip_address | string | The IP address of the customer. “Required” with post payment and credit card payment methods. Due to validation of the customer IP address, we need to receive the actual IP address of the end user within the ip_address field. More info |
| first_name | string | The customer’s first name. |
| last_name | string | The customer’s last name. |
| address1 | string | First line of customer’s provided address. |
| house_number | string | Customer’s provided house number. |
| zip_code | string | Customer’s provided zip / postal code. |
| city | string | Customer’s provided city. |
| country | string | Customer’s provided country code ISO 3166-1 |
| phone | string | Customer’s provided phone number. |
| string | Customer’s provided email address. Used to send Second Chance emails and in fraud checks. |
Creates a Direct Order
POST - /orders
{
"type": "direct",
"order_id": "My-order-id-2",
"currency": "EUR",
"amount": 1000,
"gateway": "iDEAL",
"description": "product description",
"gateway_info": {
"issuer_id": "0021"
},
"payment_options": {
"notification_url": "http://www.example.com/client/notification?type=notification",
"redirect_url": "http://www.example.com/client/notification?type=redirect",
"cancel_url": "http://www.example.com/client/notification?type=cancel",
"close_window": true
}
}JSON Response
{
"success": true,
"data": {
"transaction_id": 00002,
"order_id": "My-order-id-2",
"created": "2019-03-04T13:52:07",
"currency": "EUR",
"amount": 1000,
"description": "product description",
"var1": null,
"var2": null,
"var3": null,
"items": null,
"amount_refunded": 0,
"status": "initialized",
"financial_status": "initialized",
"reason": "",
"reason_code": "",
"fastcheckout": "NO",
"modified": "2019-03-04T13:52:07",
"customer": {
"locale": "en_US",
"first_name": null,
"last_name": null,
"address1": null,
"address2": null,
"house_number": null,
"zip_code": null,
"city": null,
"state": null,
"country": null,
"country_name": null,
"phone1": null,
"phone2": "",
"email": ""
},
"payment_details": {
"recurring_id": null,
"type": "IDEAL",
"account_id": null,
"account_holder_name": null,
"external_transaction_id": "0050003729272772",
"account_iban": "https://betalen.rabobank.nl/ideal-betaling/landingpage?random=44b2dcf080f29f6f52d05802fd76e31285ac564dc974319f0109e1d978234770&trxid=0050003729272772",
"isser_id": "0021"
},
"costs": [
{
"transaction_id": 00002,
"description": "iDEAL Transactions",
"type": "SYSTEM",
"amount":
}
],
"payment_url": "https://betalen.rabobank.nl/ideal-betaling/landingpage?random=44b2dcf080f29f6f52d05802fd76e31285ac564dc974319f0109e1d978234770&trxid=0050003729272772"
}
}Creates a direct order.
Depending on the payment method, additional information should be provided. See each payment method reference for additional information.
Supported payment methods are:
IDEAL, CREDITCARDS, PAYAFTER, EINVOICE, KLARNA, KLARNA_ACC, DIRDEB, DIRECTBANK, BANKTRANS, PAYPAL, BELFIUS, ING, KBC, ALIPAY
| Parameter | Type | Description |
|---|---|---|
| type | string | Specifies the payment flow for the checkout process. Options: direct. |
| order_id | string | The unique identifier from your system for the order. |
| currency | string | The currency ISO-4217 you want the customer to pay with. |
| amount | integer | The amount (in cents) that the customer needs to pay. |
| gateway | string | The unique gateway id to immediately direct the customer to the payment method. You retrieve these gateways using a gateway request. |
| description | string | A text which will be shown with the order in MultiSafepay Control. If the customer’s bank supports it this will also be shown on the bank statement. Max 200 characters. HTML is no longer supported. Use the ‘items’ or ‘shopping_cart’ objects for this. |
| gateway_info | object | |
| issuer_id | string | Contains the issuer_id |
| payment_options | object | |
| notification_url | string | Endpoint where we will send the notifications to. notification_url |
| notification_method | string | Sends push notification (POST,GET) default: GET. |
| redirect_url | string | Customer will be redirected to this page after a successful payment. |
| cancel_url | string | Customer will be redirected to this page after a failed payment. |
Recurring Payment
POST - /orders
{
"type": "direct",
"order_id": "My-order-id-3",
"gateway": "gatewaycode",
"recurring_id": "{recurring_id}",
"currency": "EUR",
"amount": "1000",
"description": "Test Order Description",
"payment_options": {
"notification_url": "http://www.example.com/client/notification?type=notification",
"redirect_url": "http://www.example.com/client/notification?type=redirect",
"cancel_url": "http://www.example.com/client/notification?type=cancel",
"close_window": ""
}
}JSON Response
{
"success": true,
"data": {
"transaction_id": 0000003,
"order_id": "My-order-id-3",
"created": "2019-03-04T14:11:37",
"currency": "EUR",
"amount": 1000,
"description": "Test Order Description",
"var1": null,
"var2": null,
"var3": null,
"items": "2 x : GEOMETRIC CANDLE HOLDERS",
"amount_refunded": 0,
"status": "initialized",
"financial_status": "initialized",
"reason": "",
"reason_code": "",
"fastcheckout": "NO",
"modified": "2019-03-04T14:11:37",
"customer": {
"locale": "en",
"first_name": null,
"last_name": "Test Last name",
"address1": "address 1",
"address2": "address 2",
"house_number": 22,
"zip_code": 29000,
"city": "Amsterdam ",
"state": null,
"country": "NL",
"country_name": null,
"phone1": 0208500500,
"phone2": "",
"email": "[email protected]"
},
"payment_details": {
"recurring_id": "{recurring_id}",
"type": "gatewaycode",
"account_id": 1,
"account_holder_name": "Testperson-nl",
"external_transaction_id": "00000003",
"account_iban": "IBAN Number ",
"account_bic": "BIC code"
},
"costs": [],
"payment_url": "https://payv2.multisafepay.com/connect/99wi0OTuiCaTY2nwEiEOybWpVx8MNwrJ75c/?lang=en_US",
"cancel_url": "http://www.example.com/client/notification?type=cancel&transactionid=apitool_"
}
}Recurring Payments can be done using Credit Cards (VISA, Mastercard) and SEPA Direct Debit.
iDEAL and SOFORT Banking can be used for an initial payment as well, and followed up by a recurring payment with SEPA Direct Debit. A merchant account with recurring payment enabled will receive a recurring ID in the transaction response. The recurring ID can be used for future transactions.
For more information about recurring payments, please refer to our dedicated page.
| Parameter | Type | Description |
|---|---|---|
| type | string | Specifies the payment flow for the checkout process. Options: direct. |
| gateway | string | Specifies the payment method used for the checkout process. Options: AMEX, DIRDEB, MASTERCARD, VISA. DIRDEB is to be used after initial payment with IDEAL, DIRECTBANK (Sofort) and DIRDEB. |
| order_id | string | The unique identifier from your system for the order. |
| recurring_id | integer | A previously stored recurring_id referring to a payment method to be charged again. |
| currency | string | The currency ISO-4217 you want the customer to pay with. |
| amount | integer | The amount (in cents) that the customer needs to pay. |
| description | string | A text which will be shown with the order in MultiSafepay Control. If the customer’s bank supports it this will also be shown on the bank statement. Max 200 characters. HTML is no longer supported. Use the ‘items’or ‘shopping_cart’ objects for this. |
| payment_options | object | |
| notification_url | string | Endpoint where we will send the notifications to. notification_url |
| notification_method | string | Sends push notification (POST,GET) default: GET. |
| redirect_url | string | Customer will be redirected to this page after a successful payment. |
| cancel_url | string | Customer will be redirected to this page after a failed payment. |
Split Payments
POST - /orders
{
"type": "redirect",
"order_id": "my-order-id-4",
"currency": "EUR",
"amount": "1000",
"description": "Split Payment Order",
"affiliate": {
"split_payments": [
{
"merchant": 1001001,
"fixed": 112,
"description": "Fixed fee"
},
{
"merchant": 1001001,
"percentage": 11.2,
"description": "percentage fee"
}
]
}
}JSON Response
{
"success": true,
"data": {
"order_id": "my-order-id-4",
"payment_url": "https://payv2.multisafepay.com/connect/99wi0OTuiCaTY2nwEiEOybWpVx8MNwrJ75c/?lang=en_US"
}
}The split payment tool allows you to split the amount of a transaction over several MultiSafepay Control accounts. Merchants can choose to split payments based on percentage, a fixed amount or a combination of the two.
For more information about split payments, please refer to our dedicated page.
| Parameter | Type | Description |
|---|---|---|
| type | string | Specifies the payment flow for the checkout process. Options: direct, redirect and paymentlink. |
| gateway | string | The unique gateway id to immediately direct the customer to the payment method. You retrieve these gateways using a gateway request. |
| order_id | string | The unique identifier from your system for the order. |
| currency | string | The currency (ISO-4217) you want the customer to pay with. |
| amount | integer | The amount (in cents) that the customer needs to pay. |
| description | string | A text which will be shown with the order in MultiSafepay Control. If the customer’s bank supports it this will also be shown on the bank statement. Max 200 characters. HTML is no longer supported. Use the ‘items’ or ‘shopping_cart’ objects for this. |
| payment_options | object | |
| notification_url | string | Endpoint where we will send the notifications to. notification_url |
| redirect_url | string | Customer will be redirected to this page after a successful payment. |
| cancel_url | string | Customer will be redirected to this page after a failed payment. |
| split_payments | object | |
| split_payments.merchant | integer | Affiliate AccountID of a MultiSafepay Control. |
| split_payments.percentage | float | Define a percentage of the amount to split. |
| split_payments.fixed | integer | Define amount to split in cents. |
| split_payments.description | string | Description. |
Update an order
PATCH - /orders/{order_id}
{
"status": "shipped",
"tracktrace_code": "3SMSP0123456789",
"carrier": "MSP Logistics",
"ship_date": "01-01-1911",
"reason": "Fulfilled by warehouse",
"invoice_id": "AB12345"
}JSON Response
{
"success": true,
"data": {}
}Update the order details.
| Parameter | Type | Description |
|---|---|---|
| id | string | The unique identifier of the order which should be updated. |
| status | string | The new order status. Options: cancelled, completed, shipped. |
| tracktrace_code | string | The track and trace code provided by the shipping company. |
| tracktrace_url | string | The track and trace URL provided by the shipping company. |
| carrier | string | The name of the shipping company delivering the customer’s order. |
| ship_date | string | The date that the order was shipped. |
| reason | string | Add a short free text memo to the order when setting the shipping status. |
| invoice_id | string | Update an existing order with a reference to your internal invoice id. The invoice id will be added to financial reports and exports generated within MultiSafepay Control. |
Retrieve an order
GET - /orders/{order_id}
JSON Response
{
"success": true,
"data": {
"transaction_id": 258655825,
"order_id": "{order_id}",
"created": "2019-03-01T16:12:47",
"currency": "EUR",
"amount": 200,
"description": "Test Order Description",
"var1": null,
"var2": null,
"var3": null,
"items": null,
"amount_refunded": 200,
"status": "refunded",
"financial_status": "completed",
"reason": "Successful approval/completion",
"reason_code": "",
"fastcheckout": "NO",
"modified": "2019-03-01T16:13:14",
"customer": {
"locale": "nl_NL",
"first_name": "Testperson-nl",
"last_name": "Approved",
"address1": "Neherkade",
"address2": null,
"house_number": "XI",
"zip_code": "2521VA",
"city": "Gravenhage",
"state": null,
"country": "NL",
"country_name": null,
"phone1": "0612345678",
"phone2": "",
"email": "[email protected]"
},
"payment_details": {
"recurring_id": "{Recurring_id}",
"type": "VISA",
"account_id": null,
"account_holder_name": "Testperson-nl Approved",
"external_transaction_id": 906015000050,
"last4": "1234",
"card_expiry_date": 1904
},
"costs": [
{
"transaction_id": 258656087,
"description": "Refund order 258655825 for TEST TEST",
"type": "internal",
"status": "completed",
"created": "2019-03-01T16:14:02",
"amount": 0.19
}
],
"related_transactions": [
{
"amount": 200,
"costs": [
{
"amount": 19,
"currency": "EUR",
"description": "EURO 0.19 per refund",
"status": "reserved",
"type": "SYSTEM"
}
],
"created": "2019-03-01T16:14:02",
"currency": "EUR",
"description": "Refund order 258655825 for TEST TEST",
"modified": "2019-03-01T16:14:02",
"status": "completed",
"transaction_id": 258656087
}
],
"payment_methods": [
{
"account_holder_name": "Testperson-nl Approved",
"amount": 200,
"card_expiry_date": 1904,
"currency": "EUR",
"description": "Test Order Description",
"external_transaction_id": 906015000050,
"last4": 1234,
"payment_description": "Visa",
"status": "completed",
"type": "VISA"
}
]
}
}Get order status & information. Depending on the order type or method, the structure may be different.
| Parameter | Type | Description |
|---|---|---|
| order_id | string | The unique identifier of the order to be returned. |
Dynamic Template
POST - /orders
{
"type": "redirect",
"order_id": "my-order-id-5",
"gateway": "",
"currency": "EUR",
"amount": "1000",
"description": "Test Order Description",
"manual": "false",
"payment_options": {
"notification_url": "http://www.example.com/client/notification?type=notification",
"redirect_url": "http://www.example.com/client/notification?type=redirect",
"cancel_url": "http://www.example.com/client/notification?type=cancel",
"template_id": "123456",
"template": {
"version": "1.0",
"settings": {
"hide_logo": false,
"hide_flags": false,
"hide_powered": false,
"hide_cart": false,
"hide_btn_cancel": false,
"hide_cc_logos": false,
"hide_btn_all_methods": false
},
"header": {
"logo": {
"image": ""
},
"cover": {
"image": ""
},
"background": "",
"text": "#333"
},
"body": {
"text": "#ab141b",
"background": "#fdfcfc",
"link": {
"text": "#00acf1",
"hover": {
"text": "",
"border": ""
}
}
},
"container": {
"text": "#ffffff",
"label": "#a4a3a3",
"background": "#080808",
"link": {
"text": ""
}
},
"cart": {
"text": "#333333",
"label": "#8b8b8b",
"background": "#ffffff",
"border": "#333333"
},
"payment_form": {
"text": "#ab141b",
"background": "#ffffff",
"border": "#333333",
"inputs": {
"border": "#bdbbbb",
"label": "#8b8b8b"
}
},
"buttons": {
"payment_method": {
"background": "#ffffff",
"text": "#ab141b",
"border": "#333333",
"hover": {
"background": "#ab141b",
"text": "#ffffff",
"border": ""
},
"active": {
"background": "",
"text": "",
"border": ""
}
},
"secondary": {
"background": "#00acf1",
"text": "#ffffff",
"hover": {
"background": "",
"text": ""
}
},
"primary": {
"background": "#cccccc",
"text": "#ffffff",
"hover": {
"background": "",
"text": ""
}
}
}
}
},
"customer": {
"email": "[email protected]"
}
}JSON Response
{
"success": true,
"data": {
"order_id": "my-order-id-5",
"payment_url": "https://payv2.multisafepay.com/connect/99wi0OTuiCaTY2nwEiEOybWpVx8MNwrJ75c/?lang=nl_NL"
}
}You can define the template of the MultiSafepay payment page within a transaction request. This can be done by providing a template_id of a predefined template within your MultiSafepay Control or by providing a template object structure within the transaction request. When both are provided, the template object is primary.
The template object structure needs to include the JSON CSS parameters. When sending partial CSS settings within the template structure, only the sent parameter will override the default MultiSafepay template.
When sending images within the template structure for the “logo” and “header”, you can use external references but they must be using HTTPS, otherwise they will be ignored.
| Parameter | Type | Description |
|---|---|---|
| gateway | string | The unique gateway id to immediately direct the customer to the payment method. You retrieve these gateways using a gateway request. |
| order_id | string | The unique identifier from your system for the order. |
| currency | string | The currency ISO-4217 you want the customer to pay with. |
| amount | integer | The amount (in cents) that the customer needs to pay. |
| description | string | A text which will be shown with the order in MultiSafepay Control. If the customer’s bank supports it this will also be shown on the bank statement. Max 200 characters. HTML is no longer supported. Use the ‘items’ or ‘shopping_cart’ objects for this. |
| payment_options | object | |
| notification_url | string | Endpoint where we will send the notifications to. notification_url |
| redirect_url | string | Customer will be redirected to this page after a successful payment. |
| cancel_url | string | Customer will be redirected to this page after a failed payment. |
| template | object | A template object structure.Template structure overrules template_id. |
| template_id | string | Saved template identifier. Template structure overrules template_id. |
Payment methods
This contains a description of how to use the API request and a reference for the parameters and types involved.
The right column shows examples of the specific JSON request and response which can be expected.
Our API payment methods enables you to perform different calls through which you can start a transactions
We encourage you to study this API and start implementing your custom integration against our TEST environment
For any questions, do not hesitate to contact us at [email protected]
All parameters shown are required field(s)
AfterPay
POST - /orders
{
"type": "direct",
"gateway": "AFTERPAY",
"order_id": "my-order-id-1",
"currency": "EUR",
"amount": "37380",
"description": "Test Order Description",
"var1": "",
"var2": "",
"var3": "",
"items": "",
"manual": "false",
"payment_options": {
"notification_url": "http://www.example.com/client/notification?type=notification",
"redirect_url": "http://www.example.com/client/notification?type=redirect",
"cancel_url": "http://www.example.com/client/notification?type=cancel",
"close_window": ""
},
"customer": {
"locale": "nl_NL",
"ip_address": "31.148.195.10",
"forwarded_ip": "",
"first_name": "Testperson-nl",
"last_name": "Approved",
"address1": "Neherkade",
"address2": "",
"house_number": "1/XI",
"zip_code": "2521VA",
"city": "Gravenhage",
"state": "",
"country": "NL",
"email": "[email protected]",
"referrer": "http://multisafepay-demo.com/plugingroup/dev/magento/1901/checkout/cart/",
"user_agent": "Mozilla/5.0 (Windows NT 6.3; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/38.0.2125.111 Safari/537.36"
},
"delivery": {
"first_name": "Testperson-nl",
"last_name": "Approved",
"address1": "Neherkade",
"address2": "",
"house_number": "1/XI",
"zip_code": "2521VA",
"city": "Gravenhage",
"state": "",
"country": "NL",
"phone": "0612345678",
"email": "[email protected]"
},
"gateway_info": {
"birthday": "1970-07-10",
"gender": "mr",
"phone": "0612345678",
"email": "[email protected]"
},
"shopping_cart": {
"items": [
{
"name": "Geometric Candle Holders",
"description": "",
"unit_price": "90",
"quantity": "3",
"merchant_item_id": "1111",
"tax_table_selector": "BTW21",
"weight": {
"unit": "KG",
"value": "12"
}
},
{
"name": "Nice apple",
"description": "",
"unit_price": "35",
"quantity": "1",
"merchant_item_id": "666666",
"tax_table_selector": "BTW6",
"weight": {
"unit": "KG",
"value": "20"
}
},
{
"name": "Flat Rate - Fixed",
"description": "Shipping",
"unit_price": "10.0000",
"quantity": "1",
"merchant_item_id": "msp-shipping",
"tax_table_selector": "none",
"weight": {
"unit": "KG",
"value": "0"
}
}
]
},
"checkout_options": {
"tax_tables": {
"default": {
"shipping_taxed": "true",
"rate": "0.21"
},
"alternate": [
{
"name": "BTW21",
"standalone": true,
"rules": [
{
"rate": "0.21"
}
]
},
{
"name": "BTW6",
"standalone": true,
"rules": [
{
"rate": "0.06"
}
]
},
{
"name": "BTW0",
"standalone": true,
"rules": [
{
"rate": "0.00"
}
]
},
{
"name": "0.0000",
"standalone": false,
"rules": [
{
"rate": "0"
}
]
},
{
"name": "0.0000",
"standalone": false,
"rules": [
{
"rate": "0"
}
]
},
{
"name": "FEE",
"standalone": false,
"rules": [
{
"rate": "0.00"
}
]
},
{
"name": "none",
"standalone": false,
"rules": [
{
"rate": "0.00"
}
]
},
{
"name": "2",
"standalone": true,
"rules": [
{
"rate": "0.0825",
"country": "US"
},
{
"rate": "0.08375",
"country": "US"
}
]
}
]
}
}
}JSON Response
{
"success": true,
"data": {
"transaction_id": 2340676,
"order_id": "my-order-id-1",
"created": "2017-09-29T16:13:10",
"currency": "EUR",
"amount": 26000,
"description": "Test Order Description",
"var1": null,
"var2": null,
"var3": null,
"items": "",
"amount_refunded": 0,
"status": "completed",
"financial_status": "initialized",
"reason": "",
"reason_code": "",
"fastcheckout": "NO",
"modified": "2017-09-29T16:13:10",
"customer": {
"locale": "en_US",
"first_name": "Testperson-nl",
"last_name": "Approved",
"address1": "Neherkade",
"address2": null,
"house_number": "39c",
"zip_code": "1033SC",
"city": "Gravenhage",
"state": null,
"country": "NL",
"country_name": null,
"phone1": "0612345678",
"phone2": "",
"email": "[email protected]"
},
"payment_details": {
"recurring_id": null,
"type": "",
"account_id": 10071970,
"account_holder_name": null,
"external_transaction_id": 2379429850
},
"shopping_cart": {
"items": [
{
"name": "Item demo 1",
"description": "",
"unit_price": "90.00",
"currency": "EUR",
"quantity": 2,
"merchant_item_id": 666666,
"tax_table_selector": "none",
"cashback": "",
"image": "",
"product_url": "",
"weight": {
"unit": "KG",
"value": 12
},
"options": []
},
{
"name": "Item demo 2",
"description": "",
"unit_price": "35.00",
"currency": "EUR",
"quantity": 2,
"merchant_item_id": 666666,
"tax_table_selector": "none",
"cashback": "",
"image": "",
"product_url": "",
"weight": {
"unit": "KG",
"value": 20
},
"options": []
},
{
"name": "Item shipping - Flat Rate - Fixed",
"description": "Shipping",
"unit_price": "10.00",
"currency": "EUR",
"quantity": 1,
"merchant_item_id": "msp-shipping",
"tax_table_selector": "none",
"cashback": "",
"image": "",
"product_url": "",
"weight": {
"unit": "KG",
"value": 0
},
"options": []
}
]
},
"checkout_options": {
"default": {
"shipping_taxed": true,
"rate": 0.21
},
"alternate": [
{
"standalone": true,
"name": "BTW21",
"rules": [
{
"rate": 0.21,
"country": ""
}
]
},
{
"standalone": true,
"name": "BTW6",
"rules": [
{
"rate": 0.06,
"country": ""
}
]
},
{
"standalone": true,
"name": "BTW0",
"rules": [
{
"rate": "0.00",
"country": ""
}
]
},
{
"standalone": "",
"name": "0.0000",
"rules": [
{
"rate": "0.00",
"country": ""
}
]
},
{
"standalone": "",
"name": "0.0000",
"rules": [
{
"rate": "0.00",
"country": ""
}
]
},
{
"standalone": "",
"name": "FEE",
"rules": [
{
"rate": "0.00",
"country": ""
}
]
},
{
"standalone": "",
"name": "none",
"rules": [
{
"rate": "0.00",
"country": ""
}
]
},
{
"standalone": true,
"name": 2,
"rules": [
{
"rate": 0.0825,
"country": "US"
},
{
"rate": 0.08375,
"country": "NL"
}
]
}
]
},
"order_adjustment": {
"total_adjustment": "0.00",
"total_tax": "0.00"
},
"order_total": "260.00",
"costs": [],
"payment_url": "http://www.example.com/client/?action=notification&type=redirect&transactionid=2340676",
"cancel_url": "http://www.example.com/client/?action=notification&type=cancel&transactionid=2340676"
}
}Creates an AfterPay order to be paid after delivery.
Direct transaction requires all fields completed properly
All parameters shown are required field(s)
| Parameter | Type | Description |
|---|---|---|
| type | string | Specifies the payment flow for the checkout process. Options: direct, redirect. |
| gateway | string | The unique gateway_id to immediately direct the customer to the payment method. You retrieve these gateways using a gateway request. Options: AFTERPAY. |
| order_id | string | The unique identifier from your system for the order. |
| currency | string | The currency ISO-4217 you want the customer to pay with. |
| amount | integer | The amount (in cents) that the customer needs to pay. |
| description | string | A free text description which will be shown with the order in MultiSafepay Control. If the customers bank supports it this description will also be shown on the customers bank statement. Max 200 characters. HTML is no longer supported. Use the required ‘shopping-cart’ object for this. |
| payment_options | object | Contains the redirect_url, cancel_url and notification_url |
| customer | object | Contains the personal information of the customer. Values for first_name and last_name require minimum two characters. |
| delivery | object | Contains the delivery information for the shipment. Values for first_name and last_name require minimum two characters. |
| shopping_cart | object | Contains all purchased items including tax class. |
| checkout_options | object | Contains the definitions for the VAT class. |
| gateway_info | object | Contains the issuer_id. |
| birthday | string | The birth date of the customer in the format yyyy-mm-dd. This is required for credit checks. Required in countries: DE, NL, DK, BE, AT Optional in countries: CH, NO, FI, SE. |
| phone | string | The phone number where the customer can be reached. This is required for credit checks and to contact the customer in case of non-payment. |
| string | The email address where the system can send payment instructions to the customer. | |
| gender | string | The gender salutation of the customer. Options: mr, mrs, miss. |
| personal_number - | string | The personal ID of the customer. Required in countries: FI, SE, NO Optional in countries: DE, AT, CH, BE, NL, DK. |
| ip_address | string | The IP address of the customer. “Required” with post payment and credit card payment methods. Due to validation of the customer IP address, we need to receive the actual IP address of the end user within the ip_address field. More info |
| forwarded_ip | string | The X-FORWARDED-FOR header of the customer request when using a proxy. More info |
Please note that first_name and last_name in both customer and delivery objects require minimum two characters per entry. Failing to do so might result in unexpected errors. Given the nature of this payment method, we recommend you to always require full names (not initials, abbreviations, acronyms).
Make sure you check out our dedicated documentation for AfterPay.
Alipay
POST - /orders
{
"type": "redirect",
"order_id": "my-order-id-1",
"gateway": "ALIPAY",
"currency": "EUR",
"amount": "1000",
"description": "Test Order Description",
"payment_options": {
"notification_url": "http://www.example.com/client/notification?type=notification",
"redirect_url": "http://www.example.com/client/notification?type=redirect",
"cancel_url": "http://www.example.com/client/notification?type=cancel",
"close_window": ""
},
"customer": {
"locale": "en_US"
}
}JSON Response
{
"success": true,
"data": {
"order_id": "my-order-id-1",
"payment_url": "https://payv2.multisafepay.com/connect/13oElUaESR7YS2b4gUJV9oI4tUXeb1mj1D8/?lang=nl_NL"
}
}- All parameters shown are required field(s)
| Parameter | Type | Description |
|---|---|---|
| type | string | Specifies the payment flow for the checkout process. Options: redirect, direct, paymentlink. |
| gateway | string | The unique gateway id to immediately direct the customer to the payment method. You retrieve these gateways using a gateway request. Options: ALIPAY. |
| order_id | string | The unique identifier from your system for the order. |
| currency | string | The currency (ISO-4217) you want the customer to pay with. |
| amount | integer | The amount (in cents) that the customer needs to pay. |
| description | string | A text which will be shown with the order in MultiSafepay Control. If the customer’s bank supports it this will also be shown on the bank statement. Max. 200 character. HTML is no longer supported. Use the ‘items’ or ‘shopping_cart’ objects for this. |
| payment_options | object | |
| customer | object |
Please make sure you check out our dedicated documentation for Alipay.
Bancontact
POST - /orders
{
"type": "redirect",
"order_id": "my-order-id-1",
"gateway": "MISTERCASH",
"currency": "EUR",
"amount": "1000",
"description": "Test Order Description",
"payment_options": {
"notification_url": "http://www.example.com/client/notification?type=notification",
"redirect_url": "http://www.example.com/client/notification?type=redirect",
"cancel_url": "http://www.example.com/client/notification?type=cancel",
"close_window": ""
},
"customer": {
"locale": "en_US"
}
}JSON Response
{
"success": true,
"data": {
"order_id": "my-order-id-1",
"payment_url": "https://payv2.multisafepay.com/connect/13oElUaESR7YS2b4gUJV9oI4tUXeb1mj1D8/?lang=nl_NL"
}
}- All parameters shown are required field(s)
| Parameter | Type | Description |
|---|---|---|
| type | string | Specifies the payment flow for the checkout process. Options: redirect and paymentlink. |
| gateway | string | The unique gateway_id to immediately direct the customer to the payment method. You retrieve these gateways using a gateway request. Options: MISTERCASH. |
| order_id | string | The unique identifier from your system for the order. |
| currency | string | The currency (ISO-4217) you want the customer to pay with. |
| amount | integer | The amount (in cents) that the customer needs to pay. |
| description | string | A text which will be shown with the order in MultiSafepay Control. If the customer’s bank supports it this will also be shown on the bank statement. Max. 200 characters. HTML is no longer supported. Use the ‘items’ or ‘shopping_cart’ objects for this. |
| payment_options | object | |
| customer | object |
Please make sure you check out our dedicated documentation for Bancontact.
Bank transfer
POST - /orders
{
"type": "direct",
"order_id": "my-order-id-1",
"gateway": "BANKTRANS",
"currency": "EUR",
"amount": "9743",
"description": "Test Order Description",
"payment_options": {
"notification_url": "http://www.example.com/client/notification?type=notification",
"redirect_url": "http://www.example.com/client/notification?type=redirect",
"cancel_url": "http://www.example.com/client/notification?type=cancel",
"close_window": ""
}
}JSON Response
{
"success": true,
"data": {
"transaction_id": 2340670,
"order_id": "my-order-id-1",
"created": "2017-09-29T15:55:09",
"currency": "EUR",
"amount": 9743,
"description": "product description",
"var1": null,
"var2": null,
"var3": null,
"items": null,
"amount_refunded": 0,
"status": "initialized",
"financial_status": "initialized",
"reason": "",
"reason_code": "",
"fastcheckout": "NO",
"modified": "2017-09-29T15:55:09",
"customer": {
"locale": "en_US",
"first_name": null,
"last_name": null,
"address1": null,
"address2": null,
"house_number": null,
"zip_code": null,
"city": null,
"state": null,
"country": null,
"country_name": null,
"phone1": null,
"phone2": "",
"email": ""
},
"payment_details": {
"recurring_id": null,
"type": "BANKTRANS",
"account_id": null,
"account_holder_name": "",
"external_transaction_id": "9201727123406700"
},
"costs": [
{
"transaction_id": 413281,
"description": "",
"type": "SYSTEM",
"amount": 0
}
],
"gateway_info": {
"reference": "5190692604051530",
"issuer_name": "DB",
"destination_holder_name": "MultiSafepay",
"destination_holder_city": "Amsterdam",
"destination_holder_country": "NL",
"destination_holder_iban": "NL63DEUT7351103321",
"destination_holder_swift": "DEUTNL2NXXX",
"account_holder_name": "{customer's name here if provided in transaction request}",
"account_holder_city": "{customer's city here if provided in transaction request}",
"account_holder_country": "{customer's country here if provided in transaction request}"
},
"payment_url": "https://www.example.com/client/success?transactionid=my-order-id-1",
"cancel_url": "https://www.example.com/client/failed?transactionid=my-order-id-1"
}
}- All parameters shown are required field(s)
| Parameter | Type | Description |
|---|---|---|
| type | string | Specifies the payment flow for the checkout process. Options: direct, redirect, checkout, paymentlink. |
| gateway | string | The unique gateway id to immediately direct the customer to the payment method. You retrieve these gateways using a gateway request. Options: BANKTRANS. |
| order_id | string | The unique identifier from your system for the order. |
| currency | string | The currency (ISO-4217) you want the customer to pay with. |
| amount | integer | The amount (in cents) that the customer needs to pay. |
| description | string | A text which will be shown with the order in MultiSafepay Control. If the customer’s bank supports it this will also be shown on the bank statement. Max 200 characters. HTML is no longer supported. Use the ‘items’ or ‘shopping_cart’ objects for this. |
| payment_options | object | |
| customer | object |
In the JSON response for a direct transaction, the following is important in order to send instructions to the customer by yourself. Please be aware that all of the parameters can be different for every single transaction. Do not store this information other than for a specific transaction.
| Parameter | Type | Description |
|---|---|---|
| gateway_info | object | Contains the information for the customer in order to pay for the transaction. |
| reference | string | A unique number the customer must mention within the bank transfer in order to have the payment recognized by MultiSafepay. |
| issuer_name | string | The name of our bank to send the money to. |
| destination_holder_name | string | The account holder name registered to our bank account. |
| destination_holder_city | string | The city which our bank account is registered in. |
| destination_holder_country | string | The country which our bank account is registered in. |
| destination_holder_iban | string | The International Bank Account Number to send the money to. |
| destination_holder_swift | string | The Bank Identification Code to send the money to. |
| account_holder_name | string | The customer’s name here if provided in transaction request. |
| account_holder_city | string | The customer’s city here if provided in transaction request. |
| account_holder_country | string | The customer’s country here if provided in transaction request. |
Please make sure you check out our dedicated documentation for bank transfers.
Belfius
POST - /orders
{
"type": "redirect",
"order_id": "my-order-id-1",
"gateway": "BELFIUS",
"currency": "EUR",
"amount": "1000",
"description": "Test Order Description",
"payment_options": {
"notification_url": "http://www.example.com/client/notification?type=notification",
"redirect_url": "http://www.example.com/client/notification?type=redirect",
"cancel_url": "http://www.example.com/client/notification?type=cancel",
"close_window": ""
},
"customer": {
"locale": "en_US"
}
}JSON Response
{
"success": true,
"data": {
"order_id": "my-order-id-1",
"payment_url": "https://payv2.multisafepay.com/connect/13oElUaESR7YS2b4gUJV9oI4tUXeb1mj1D8/?lang=nl_NL"
}
}- All parameters shown are required field(s)
| Parameter | Type | Description |
|---|---|---|
| type | string | Specifies the payment flow for the checkout process. Options: direct , redirect , paymentlink. |
| gateway | string | The unique gateway id to immediately direct the customer to the payment method. You retrieve these gateways using a gateway request. Options: BELFIUS. |
| order_id | string | The unique identifier from your system for the order. |
| currency | string | The currency ISO-4217 you want the customer to pay with. |
| amount | integer | The amount (in cents) that the customer needs to pay. |
| description | string | A text which will be shown with the order in MultiSafepay Control. If the customer’s bank supports it this will also be shown on the customer’s bank statement. Max. 200 characters. HTML is no longer supported. Use the ‘items’or ‘shopping_cart’ objects for this. |
| payment_options | object | |
| customer | object |
Please make sure you check out our dedicated documentation for Belfius.
Credit Cards
POST - /orders
{
"type": "direct",
"order_id": "my-order-id-1",
"gateway": "CREDITCARD",
"currency": "EUR",
"amount": "9743",
"description": "Test Order Description",
"payment_options": {
"notification_url": "http://www.example.com/client/notification?type=notification",
"redirect_url": "http://www.example.com/client/notification?type=redirect",
"cancel_url": "http://www.example.com/client/notification?type=cancel",
"close_window": ""
},
"gateway_info": {
"card_number": "4012001038443335",
"card_holder_name": "Test Holder Name",
"card_expiry_date": "2022",
"card_cvc": "123"
},
"customer": {
"locale": "en_US",
"ip_address": "31.148.195.10",
"forwarded_ip": "",
"first_name": "John",
"last_name": "Doe",
"address1": "Neherkade",
"house_number": "XI",
"zip_code": "2521VA",
"city": "Gravenhage",
"state": "",
"country": "NL",
"email": "[email protected]",
"referrer": "http://example.com",
"user_agent": "Mozilla/5.0 (Windows NT 6.3; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/38.0.2125.111 Safari/537.36"
}
}JSON Response
{
"transaction_id": 0,
"order_id": "",
"created": "",
"modified": "",
"recurring_id": "",
"gateway": "",
"currency": "",
"amount": "",
"description": "",
"var1": "",
"var2": "",
"var3": "",
"amount_refunded": 0,
"status": "",
"financial_status": "",
"reason": "",
"reason_code": "",
"fastcheckout": "",
"order_total": "",
"html_form": "",
"payment_url": "",
"cancel_url": "",
"customer": {
"locale": "",
"ip_address": "",
"forwarded_ip": "",
"referrer": "",
"user_agent": "",
"first_name": "",
"last_name": "",
"company": false,
"company_name": "",
"address1": "",
"address2": "",
"house_number": "",
"zip_code": "",
"city": "",
"state": "",
"country": "",
"phone": "",
"email": "",
"disable_send_email": false
},
"gateway_info": {
"issuer_id": "",
"account_id": "",
"account_holder_name": "",
"account_holder_city": "",
"account_holder_country": "",
"account_holder_iban": "",
"account_holder_swift": "",
"account_holder_bic": "",
"personal_number": "",
"gender": "",
"phone": "",
"referrer": "",
"email": "",
"user_agent": "",
"card_number": "",
"card_holder_name": "",
"card_expiry_date": "",
"card_cvc": "",
"emandate": "",
"qr_size": "",
"company": "",
"po_number": "",
"coc": "",
"vat": "",
"collecting_flow": "",
"action_on_declined": "",
"company_type": "",
"term_url": "",
"birthday": "",
"bank_account": ""
},
"payment_details": {
"recurring_id": "",
"type": "",
"card_expiry_date": false,
"last4": false,
"account_id": "",
"account_holder_name": false,
"external_transaction_id": false,
"account_iban": false,
"account_bic": false
},
"shopping_cart": {
"items": [
{
"name": "",
"description": "",
"unit_price": "",
"currency": "",
"quantity": 0,
"created": "",
"merchant_item_id": "",
"tax_table_selector": "",
"cashback": "",
"image": "",
"product_url": "",
"weight": {
"unit": 0,
"value": ""
}
}
]
},
"checkout_options": {
"no_shipping_method": false,
"use_shipping_notification": false,
"tax_tables": {
"default": {
"shipping_taxed": false,
"rate": "",
"rules": [
{
"rate": 0,
"country": "",
"world_area": false
}
]
},
"alternate": [
{
"standalone": false,
"name": "",
"rate": "",
"rules": [
{
"rate": 0,
"country": "",
"world_area": false
}
]
}
]
},
"rounding_policy": [
{
"mode": "",
"rule": ""
}
],
"shipping_methods": [
{
"flat_rate_shipping": [
{
"name": "",
"price": "",
"currency": "",
"allowed_areas": null,
"excluded_areas": null,
"id": "",
"type": "",
"provider": ""
}
],
"pickup": [
{
"name": "",
"price": "",
"currency": "",
"id": "",
"type": "",
"provider": ""
}
]
}
]
},
"order_adjustment": {
"total_adjustment": "",
"total_tax": ""
},
"costs": [
{
"transaction_id": 0,
"description": "",
"type": "",
"amount": "",
"status": "",
"created": ""
}
]
}- All parameters shown are required field(s)
| Parameter | Type | Description |
|---|---|---|
| type | string | Specifies the payment flow for the checkout process. Options: direct. |
| gateway | string | The unique gateway id to immediately direct the customer to the payment method. You retrieve these gateways using a gateway request. Options: CREDITCARD, VISA, MASTERCARD, MAESTRO, AMEX. |
| order_id | string | The unique identifier from your system for the order. |
| currency | string | The currency ISO-4217 you want the customer to pay with. |
| amount | integer | The amount (in cents) that the customer needs to pay. |
| description | string | A text which will be shown with the order in MultiSafepay Control. If the customer’s bank supports it this will also be shown on the bank statement. Max. 200 characters. HTML is no longer supported. Use the ‘items’ or ‘shopping_cart’ objects for this. |
| payment_options | object | Contains the redirect_url, cancel_url and notification_url. |
| customer | object | Contains the personal information of the customer. |
| gateway_info | object | Contains the extra card information. |
| card_number | string | Full credit card number. |
| card_holder_name | string | Name on credit card. |
| card_expiry_date | string | Card expiry date. |
| card_cvc | string | Card CVC number. This might vary depending of the card type. Some cards like MAESTRO may not be required. |
| ip_address | string | The IP address of the customer. “Required” with post payment and credit card payment methods. Due to validation of the customer IP address, we need to receive the actual IP address of the end user within the ip_address field. More info |
| forwarded_ip | string | The X-FORWARDED-FOR header of the customer request when using a proxy. More info |
Please make sure you check out our dedicated documentation for credit cards
Direct Debit
POST - /orders
{
"type": "direct",
"order_id": "my-order-id-1",
"gateway": "DIRDEB",
"currency": "EUR",
"amount": "9743",
"description": "Test Order Description",
"payment_options": {
"notification_url": "http://www.example.com/client/notification?type=notification",
"redirect_url": "http://www.example.com/client/notification?type=redirect",
"cancel_url": "http://www.example.com/client/notification?type=cancel",
"close_window": ""
},
"customer": {
"locale": "en_US",
"ip_address": "31.148.195.10",
"forwarded_ip": ""
},
"gateway_info": {
"account_id": "NL87ABNA0000000001",
"account_holder_name": "J Janse",
"account_holder_city": "Amsterdam",
"account_holder_country": "NL",
"account_holder_iban": "NL87ABNA0000000001",
"account_holder_bic": "NL",
"emandate": "madateID"
}
}JSON Response
{
"success": true,
"data": {
"transaction_id": 259898679,
"order_id": "y-order-id-1",
"created": "2019-03-08T09:23:46",
"currency": "EUR",
"amount": 9743,
"description": "Test order description",
"var1": null,
"var2": null,
"var3": null,
"items": "",
"amount_refunded": 0,
"status": "initialized",
"financial_status": "initialized",
"reason": "",
"reason_code": "",
"fastcheckout": "NO",
"modified": "2019-03-08T09:23:46",
"customer": {
"locale": "en_US",
"first_name": null,
"last_name": null,
"address1": null,
"address2": null,
"house_number": null,
"zip_code": null,
"city": null,
"state": null,
"country": null,
"country_name": null,
"phone1": null,
"phone2": "",
"email": ""
},
"payment_details": {
"recurring_id": "",
"type": "DIRDEB",
"account_id": "NL87ABNA0000000001",
"account_holder_name": "J Janse",
"external_transaction_id": "6190662598986790",
"account_iban": "NL87ABNA0000000001",
"account_bic": "ABNANL01"
},
"costs": [
{
"transaction_id": 279354751,
"description": "0.3 For Direct Debit Transactions",
"type": "SYSTEM",
"amount": 0.3
}
],
"payment_url": "https://www.example.com/client/notification?type=redirect&transactionid=my-order-id-1",
"cancel_url": "https://www.example.com/client/notification?type=cancel&transactionid=my-order-id-1"
}
}When submitting a Direct Debit, the transaction data is checked.
- If approved, we return the status
initialized. - After midnight, the transaction will be forwarded to our bank and the status changes to
uncleared. Once the funds are received on our bank account, the status changes to
completed.All parameters shown are required field(s)
| Parameter | Type | Description |
|---|---|---|
| type | string | Specifies the payment flow for the checkout process. Options: direct, redirect, checkout, paymentlink. |
| gateway | string | The unique gateway id to immediately direct the customer to the payment method. You retrieve these gateways using a gateway request. Options: DIRDEB. |
| order_id | string | The unique identifier from your system for the order. |
| currency | string | The currency (ISO-4217) you want the customer to pay with. |
| amount | integer | The amount (in cents) that the customer needs to pay. |
| description | string | A text which will be shown with the order in MultiSafepay Control. If the customer’s bank supports it this will also be shown on the bank statement. Max. 200 characters. HTML is no longer supported. Use the ‘items’ or ‘shopping_cart’ objects for this. |
| payment_options | object | Contains the redirect_url, cancel_url and notification_url |
| customer | object | Contains the personal information of the customer. |
| gateway_info | object | |
| account_id | string | IBAN to be charged for the transaction. |
| account_holder_name | string | Name of the owner of the bank account to be charged for the transaction. |
| account_holder_city | string | Place where the owner of the bank account to be charged for the transaction lives. |
| account_holder_country | string | Country where the owner of the bank account to be charged for the transaction lives. |
| account_holder_iban | string | IBAN to be charged for the transaction. |
| account_holder_swift | string | SWIFT of the bank account to be charged for the transaction. |
| account_holder_bic | string | BIC of the bank account to be charged for the transaction. |
| emandate | string | For your own adminstration, put the e-mandate here. |
| ip_address | string | The IP address of the customer. “Required” with post payment and credit card payment methods. Due to validation of the customer IP address, we need to receive the actual IP address of the end user within the ip_address field. More info |
| forwarded_ip | string | The X-FORWARDED-FOR header of the customer request when using a proxy. More info |
Please make sure you check out our dedicated documentation for Direct Debit.
Dotpay
POST - /orders
{
"type": "redirect",
"order_id": "my-order-id-1",
"gateway": "DOTPAY",
"currency": "EUR",
"amount": "1000",
"description": "Test Order Description",
"payment_options": {
"notification_url": "http://www.example.com/client/notification?type=notification",
"redirect_url": "http://www.example.com/client/notification?type=redirect",
"cancel_url": "http://www.example.com/client/notification?type=cancel",
"close_window": ""
},
"customer": {
"locale": "en_US"
}
}JSON Response
{
"success": true,
"data": {
"order_id": "my-order-id-1",
"payment_url": "https://payv2.multisafepay.com/connect/13oElUaESR7YS2b4gUJV9oI4tUXeb1mj1D8/?lang=nl_NL"
}
}- All parameters shown are required field(s)
| Parameter | Type | Description |
|---|---|---|
| type | string | Specifies the payment flow for the checkout process. Options: redirect. |
| gateway | string | The unique gateway id to immediately direct the customer to the payment method. You retrieve these gateways using a gateway request. Options: DOTPAY. |
| order_id | string | The unique identifier from your system for the order. |
| currency | string | The currency ISO-4217 you want the customer to pay with. |
| amount | integer | The amount (in cents) that the customer needs to pay. |
| description | string | A text which will be shown with the order in MultiSafepay Control. If the customer’s bank supports it this will also be shown on the bank statement. Max. 200 characters. HTML is no longer supported. Use the ‘items’ or ‘shopping_cart’ objects for this. |
| payment_options | object | |
| customer | object |
Please make sure you check out our dedicated documentation for Dotpay.
E-invoicing
POST - /orders
{
"type": "direct",
"gateway": "EINVOICE",
"order_id": "my-order-id-1",
"currency": "EUR",
"amount": "26000",
"description": "Test Order Description",
"var1": "",
"var2": "",
"var3": "",
"items": "",
"manual": "false",
"gateway_info": {
"birthday": "1980-01-30",
"bankaccount": "0417164300",
"phone": "0208500500",
"email": "[email protected]"
},
"payment_options": {
"notification_url": "http://www.example.com/client/notification?type=notification",
"redirect_url": "http://www.example.com/client/notification?type=redirect",
"cancel_url": "http://www.example.com/client/notification?type=cancel",
"close_window": ""
},
"customer": {
"locale": "us",
"ip_address": "31.148.195.10",
"forwarded_ip": "",
"first_name": "Testperson-nl",
"last_name": "Approved",
"address1": "Neherkade",
"address2": "",
"house_number": "39c",
"zip_code": "1033 SC",
"city": "Gravenhage",
"state": "",
"country": "NL",
"email": "[email protected]",
"referrer": "http://www.example.com",
"user_agent": "Mozilla/5.0 (Windows NT 6.3; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/38.0.2125.111 Safari/537.36"
},
"delivery": {
"first_name": "Testperson-nl",
"last_name": "Approved",
"address1": "Neherkade",
"address2": "",
"house_number": "39c",
"zip_code": "1033 SC",
"city": "Gravenhage",
"state": "",
"country": "NL",
"phone": "",
"email": ""
},
"shopping_cart": {
"items": [
{
"name": "Item demo 1",
"description": "",
"unit_price": "90",
"quantity": "2",
"merchant_item_id": "666666",
"tax_table_selector": "none",
"weight": {
"unit": "KG",
"value": "12"
}
},
{
"name": "Item demo 2",
"description": "",
"unit_price": "35",
"quantity": "2",
"merchant_item_id": "666666",
"tax_table_selector": "none",
"weight": {
"unit": "KG",
"value": "20"
}
},
{
"name": "Item shipping - Flat Rate - Fixed",
"description": "Shipping",
"unit_price": "10",
"quantity": "1",
"merchant_item_id": "msp-shipping",
"tax_table_selector": "none",
"weight": {
"unit": "KG",
"value": "0"
}
}
]
},
"checkout_options": {
"tax_tables": {
"default": {
"shipping_taxed": "true",
"rate": "0.21"
},
"alternate": [
{
"name": "BTW21",
"standalone": true,
"rules": [
{
"rate": "0.21"
}
]
},
{
"name": "BTW6",
"standalone": true,
"rules": [
{
"rate": "0.06"
}
]
},
{
"name": "BTW0",
"standalone": true,
"rules": [
{
"rate": "0.00"
}
]
},
{
"name": "0.0000",
"standalone": false,
"rules": [
{
"rate": "0"
}
]
},
{
"name": "0.0000",
"standalone": false,
"rules": [
{
"rate": "0"
}
]
},
{
"name": "FEE",
"standalone": false,
"rules": [
{
"rate": "0.00"
}
]
},
{
"name": "none",
"standalone": false,
"rules": [
{
"rate": "0.00"
}
]
},
{
"name": "2",
"standalone": true,
"rules": [
{
"rate": "0.0825",
"country": "US"
},
{
"rate": "0.08375",
"country": "NL"
}
]
}
]
}
}
}JSON Response
{
"success": true,
"data": {
"transaction_id": 2340676,
"order_id": "my-order-id-1",
"created": "2017-09-29T16:13:10",
"currency": "EUR",
"amount": 26000,
"description": "Test Order Description",
"var1": null,
"var2": null,
"var3": null,
"items": "",
"amount_refunded": 0,
"status": "completed",
"financial_status": "initialized",
"reason": "",
"reason_code": "",
"fastcheckout": "NO",
"modified": "2017-09-29T16:13:10",
"customer": {
"locale": "en_US",
"first_name": "Testperson-nl",
"last_name": "Approved",
"address1": "Neherkade",
"address2": null,
"house_number": "39c",
"zip_code": "1033SC",
"city": "Gravenhage",
"state": null,
"country": "NL",
"country_name": null,
"phone1": "0612345678",
"phone2": "",
"email": "[email protected]"
},
"payment_details": {
"recurring_id": null,
"type": "",
"account_id": 10071970,
"account_holder_name": null,
"external_transaction_id": 2379429850
},
"shopping_cart": {
"items": [
{
"name": "Item demo 1",
"description": "",
"unit_price": "90.00",
"currency": "EUR",
"quantity": 2,
"merchant_item_id": 666666,
"tax_table_selector": "none",
"cashback": "",
"image": "",
"product_url": "",
"weight": {
"unit": "KG",
"value": 12
},
"options": []
},
{
"name": "Item demo 2",
"description": "",
"unit_price": "35.00",
"currency": "EUR",
"quantity": 2,
"merchant_item_id": 666666,
"tax_table_selector": "none",
"cashback": "",
"image": "",
"product_url": "",
"weight": {
"unit": "KG",
"value": 20
},
"options": []
},
{
"name": "Item shipping - Flat Rate - Fixed",
"description": "Shipping",
"unit_price": "10.00",
"currency": "EUR",
"quantity": 1,
"merchant_item_id": "msp-shipping",
"tax_table_selector": "none",
"cashback": "",
"image": "",
"product_url": "",
"weight": {
"unit": "KG",
"value": 0
},
"options": []
}
]
},
"checkout_options": {
"default": {
"shipping_taxed": true,
"rate": 0.21
},
"alternate": [
{
"standalone": true,
"name": "BTW21",
"rules": [
{
"rate": 0.21,
"country": ""
}
]
},
{
"standalone": true,
"name": "BTW6",
"rules": [
{
"rate": 0.06,
"country": ""
}
]
},
{
"standalone": true,
"name": "BTW0",
"rules": [
{
"rate": "0.00",
"country": ""
}
]
},
{
"standalone": "",
"name": "0.0000",
"rules": [
{
"rate": "0.00",
"country": ""
}
]
},
{
"standalone": "",
"name": "0.0000",
"rules": [
{
"rate": "0.00",
"country": ""
}
]
},
{
"standalone": "",
"name": "FEE",
"rules": [
{
"rate": "0.00",
"country": ""
}
]
},
{
"standalone": "",
"name": "none",
"rules": [
{
"rate": "0.00",
"country": ""
}
]
},
{
"standalone": true,
"name": 2,
"rules": [
{
"rate": 0.0825,
"country": "US"
},
{
"rate": 0.08375,
"country": "NL"
}
]
}
]
},
"order_adjustment": {
"total_adjustment": "0.00",
"total_tax": "0.00"
},
"order_total": "260.00",
"costs": [],
"payment_url": "http://www.example.com/client/?action=notification&type=redirect&transactionid=2340676",
"cancel_url": "http://www.example.com/client/?action=notification&type=cancel&transactionid=2340676"
}
}Creates an E-Invoice order to be paid after delivery.
- All parameters shown are required field(s)
| Parameter | Type | Description |
|---|---|---|
| type | string | Specifies the payment flow for the checkout process. Options: direct, redirect. |
| gateway | string | The unique gateway_id to immediately direct the customer to the payment method. You retrieve these gateways using a gateway request. Options: EINVOICE. |
| order_id | string | The unique identifier from your system for the order. |
| currency | string | The currency ISO-4217 you want the customer to pay with. |
| amount | integer | The amount (in cents) that the customer needs to pay. |
| description | string | A text which will be shown with the order in MultiSafepay Control. If the customer’s bank supports it this will also be shown on the bank statement. Max. 200 characters. HTML is no longer supported. Use the ‘items’ or ‘shopping_cart’ objects for this. |
| payment_options | object | Contains the redirect_url, cancel_url and notification_url |
| customer | object | Contains the personal information of the customer. Values for first_name and last_name require minimum two characters. |
| delivery | object | Contains the delivery information for the shipment. Values for first_name and last_name require minimum two characters. |
| shopping_cart | object | Contains all order rules and applicable tax classes. |
| checkout_options | object | Contains the definitions for the VAT class. |
| gateway_info | object | Contains the issuer_id. |
| birthday | string | The birthdate of the customer in the format yyyy-mm-dd. |
| bank_account | string | The formatted IBAN for the customer. This is required for credit checks. |
| phone | string | The phone number where the customer can be reached. This is required for credit checks and to contact the customer in case of non-payment. |
| string | The email address to which the system can send payment instructions to the customer. | |
| ip_address | string | The IP address of the customer. “Required” with post payment and credit card payment methods. Due to validation of the customer IP address, we need to receive the actual IP address of the end user within the ip_address field. More info |
| forwarded_ip | string | The X-FORWARDED-FOR header of the customer request when using a proxy. More info |
Please note that first_name and last_name in both customer and delivery objects require minimum two characters per entry. Failing to do so might result in unexpected errors. Given the nature of this payment method, we recommend you to always require full names (not initials, abbreviations, acronyms).
Make sure you check out our dedicated documentation for E-Invoicing.
EPS
POST - /orders
{
"type": "redirect",
"order_id": "my-order-id-1",
"gateway": "EPS",
"currency": "EUR",
"amount": "1000",
"description": "Test Order Description",
"payment_options": {
"notification_url": "http://www.example.com/client/notification?type=notification",
"redirect_url": "http://www.example.com/client/notification?type=redirect",
"cancel_url": "http://www.example.com/client/notification?type=cancel",
"close_window": ""
},
"customer": {
"locale": "en_US"
}
}JSON Response
{
"success": true,
"data": {
"order_id": "my-order-id-1",
"payment_url": "https://payv2.multisafepay.com/connect/13oElUaESR7YS2b4gUJV9oI4tUXeb1mj1D8/?lang=nl_NL"
}
}- All parameters shown are required field(s)
| Parameter | Type | Description |
|---|---|---|
| type | string | Specifies the payment flow for the checkout process. Options: redirect. |
| gateway | string | The unique gateway id to immediately direct the customer to the payment method. You retrieve these gateways using a gateway request. Options: EPS. |
| order_id | string | The unique identifier from your system for the order. |
| currency | string | The currency (ISO-4217) you want the customer to pay with. |
| amount | integer | The amount (in cents) that the customer needs to pay. |
| description | string | A text which will be shown with the order in MultiSafepay Control. If the customer’s bank supports it this will also be shown on the customers bank statement. HTML is no longer supported. Use the ‘items’ or ‘shopping_cart’ objects for this. |
| payment_options | object | |
| customer | object |
Please make sure you check out our dedicated documentation for EPS.
Gift card
POST - / order
{
"type": "redirect",
"order_id": "my-order-id",
"gateway": "VVVGIFTCRD",
"currency": "EUR",
"amount": "1000",
"description": "Test Order Description",
"manual": "false",
"payment_options": {
"notification_url": "http://www.example.com/client/json-live/notification?type=notification",
"redirect_url": "http://www.example.comclient/json-live/notification?type=redirect",
"cancel_url": "http://www.example.com/client/json-live/notification?type=cancel",
"close_window": ""
},
"customer": {
"locale": "nl_NL",
"ip_address": "89.20.162.110",
"country": "NL",
"email": "[email protected]"
}
}JSON Response
{ "success": true, "data": { "order_id": "my-order-id", "payment_url": "https://payv2.multisafepay.com/connect/99wi0OTuiCaTY2nwEiEOybWpVx8MNwrJ75c/?lang=nl_NL" } }
- All parameters shown are required field(s)
| Parameter | Type | Description |
|---|---|---|
| type | string | Specifies the payment flow for the checkout process. Options: redirect. |
| gateway | string | The unique gateway id to immediately direct the customer to the payment method. You retrieve these gateways using a gateway request. All gateway name options of our standard gift cards are shown below. Note: we will only preselect the gift card supplied in the gateway. |
| order_id | string | The unique identifier from your system for the order. |
| currency | string | The currency ISO-4217 you want the customer to pay with. |
| amount | integer | The amount (in cents) that the customer needs to pay. |
| description | string | A free text description which will be shown with the order in MultiSafepay Control. If the customers bank supports it this description will also be shown on the customer`s bank statement. |
| payment_options | object | |
| notification_url | string | Endpoint where we will send the notifications to. notification_url |
| redirect_url | string | Customer will be redirected to this page after a successful payment. |
| cancel_url | string | Customer will be redirected to this page after a failed payment. |
| customer | object | |
| locale | string | Displays the correct language and payment methods on the Payment page. It also has an influence on sending the set email templates. Use the format ab_CD with ISO 639 language codes and ISO 3166 country codes. Default: en_US. |
| ip_address | string | The IP address of the customer. “Required” with post payment and credit card payment methods. Due to validation of the customer IP address, we need to receive the actual IP address of the end user within the ip_address field. More info |
| country | string | Customer’s provided country code ISO 3166-1 |
| string | Customer’s provided email address. Used to send Second Chance emails and in fraud checks. |
The gateway names of the standard gift cards MultiSafepay offers
| Gift card name | Gateway name, gift card | |
|---|---|---|
| Nationaletuinbon | NATNLETUIN | |
| Goodcard | GOODCARD | |
| Fashioncheque | FASHIONCHQ | |
| Fietsenbon | FIETSENBON | |
| VVV Cadeaukaart | VVVGIFTCRD | |
| Nationaleverwencadeaubon | NATNLVRWCB | |
| Webshopgiftcard | WEBSHOPGFT | |
| Vuur & rook gift card | VRGIFTCARD | |
| Wijncadeau | WIJNCADEAU | |
| Yourgift | YOURGIFT | |
| Fashiongiftcard | FASHIONGFT | |
| Sportenfit | SPORTENFIT | |
| Gezondheidsbon | GEZONDHEID | |
| Babygiftcard | BABYGFTCRD | |
| Boekenbon | BOEKENBON | |
| Degrotespeelgoedwinkel | DEGROTESPL | |
| Erotiekbon | EROTIEKBON | |
| Parfumcadeaukaart | PARFUMCADE | |
| Parfumnl | PARFUMNL | |
| Beautyandwellness | BEAUTYWELL | |
| Bloemencadeaukaart | BLOEMENCAD | |
| Nationale bioscoopbon | NATNLBIOSC | |
| Goodcard | GOODCARD | |
| Givacard | Branded gift cards will provide a gateway name upon release of the personilized gift card by our development team. |
Please make sure you check out our dedicated documentation for gift cards.
Giropay
POST - /orders
{
"type": "redirect",
"order_id": "my-order-id-1",
"gateway": "GIROPAY",
"currency": "EUR",
"amount": "1000",
"description": "Test Order Description",
"payment_options": {
"notification_url": "http://www.example.com/client/notification?type=notification",
"redirect_url": "http://www.example.com/client/notification?type=redirect",
"cancel_url": "http://www.example.com/client/notification?type=cancel",
"close_window": ""
},
"customer": {
"locale": "en_US"
}
}JSON Response
{
"success": true,
"data": {
"order_id": "my-order-id-1",
"payment_url": "https://payv2.multisafepay.com/connect/13oElUaESR7YS2b4gUJV9oI4tUXeb1mj1D8/?lang=nl_NL"
}
}- All parameters shown are required field(s)
| Parameter | Type | Description |
|---|---|---|
| type | string | Specifies the payment flow for the checkout process. Options: redirect. |
| gateway | string | The unique gateway id to immediately direct the customer to the payment method. You retrieve these gateways using a gateway request. Options: GIROPAY. |
| order_id: | string | The unique identifier from your system for the order. |
| currency: | string | The currency ISO-4217 you want the customer to pay with. |
| amount: | integer | The amount (in cents) that the customer needs to pay. |
| description: | string | A text which will be shown with the order in MultiSafepay Control. If the customer’s bank supports it this will also be shown on the bank statement. Max 200 characters. HTML is no longer supported. Use the ‘items’ or ‘shopping_cart’ objects for this. |
| payment_options: | object | |
| customer | object |
Please make sure you check out our dedicated documentation for Giropay.
iDEAL /-Redirect
POST - /orders
{
"type": "redirect",
"order_id": "my-order-id-1",
"gateway": "IDEAL",
"currency": "EUR",
"amount": "1000",
"description": "Test Order Description",
"payment_options": {
"notification_url": "http://www.example.com/client/notification?type=notification",
"redirect_url": "http://www.example.com/client/notification?type=redirect",
"cancel_url": "http://www.example.com/client/notification?type=cancel",
"close_window": ""
},
"customer": {
"locale": "en_US"
}
}JSON Response
{
"success": true,
"data": {
"order_id": "my-order-id-1",
"payment_url": "https://payv2.multisafepay.com/connect/13oElUaESR7YS2b4gUJV9oI4tUXeb1mj1D8/?lang=nl_NL"
}
}- All parameters shown are required field(s)
| Parameter | Type | Description |
|---|---|---|
| type | string | Specifies the payment flow for the checkout process. Options: direct, redirect, checkout, paymentlink. |
| gateway | string | The unique gateway id to immediately direct the customer to the payment method. You retrieve these gateways using a gateway request. Options: IDEAL. |
| order_id | string | The unique identifier from your system for the order. |
| currency | string | The currency ISO-4217 you want the customer to pay with. |
| amount | integer | The amount (in cents) that the customer needs to pay. |
| description | string | A free text description which will be shown with the order in MultiSafepay Control. If the customers bank supports it this description will also be shown on the customer`s bank statement. |
| payment_options | object | |
| notification_url | string | Endpoint where we will send the notifications to. notification_url |
| redirect_url | string | Customer will be redirected to this page after a successful payment. |
| cancel_url | string | Customer will be redirected to this page after a failed payment. |
| customer | object | |
| locale | string | Displays the correct language and payment methods on the Payment page. It also has an influence on sending the set email templates. Use the format ab_CD with ISO 639 language codes and ISO 3166 country codes. Default: en_US. |
iDEAL /-Direct
Supplying an issuer is required only when you submit your request as direct. The customer will be redirected to the selected bank to proceed with finalizing the payment.
POST - /orders
{
"type": "direct",
"order_id": "apitool_504957",
"currency": "EUR",
"amount": 1000,
"gateway": "iDEAL",
"description": "product description",
"custom_info": {},
"gateway_info": {
"issuer_id": "0031"
},
"payment_options": {
"notification_url": "http://www.example.com/client/notification?type=notification",
"redirect_url": "http://www.example.com/client/notification?type=redirect",
"cancel_url": "http://www.example.com/client/notification?type=cancel",
"close_window": ""
}
}JSON Response
{
"success": true,
"data": {
"order_id": "apitool_504957",
"payment_url": "https://www.selected-bank.nl/en/ideal-betalen/index.html?randomizedstring=000000&trxid=00000000"
}
}- All parameters shown are required field(s)
| Parameter | Type | Description |
|---|---|---|
| type | string | Direct. |
| gateway_info | object | |
| issuer_id | integer | The unique identifier of the issuer |
Please make sure you check out our dedicated documentation for iDEAL.
iDEAL QR
POST - /orders
{
"type": "direct",
"order_id": "my-order-id-1",
"gateway": "iDEALQR",
"currency": "EUR",
"amount": "1000",
"description": "Test Order Description",
"payment_options": {
"notification_url": "http://www.example.com/client/notification?type=notification",
"redirect_url": "http://www.example.com/client/notification?type=redirect",
"cancel_url": "http://www.example.com/client/notification?type=cancel",
"close_window": ""
},
"gateway_info": {
"qr_size": 250,
"allow_multiple": false,
"allow_change_amount": false,
"max_amount": 1000
},
"customer": {
"locale": "en_US"
}
}JSON Response
{
"success": true,
"data": {
"order_id": "ideal-test",
"payment_url": "https://testpayv2.multisafepay.com/connect/896rZ0IGzhJoP2XQdqzMtHYnIG32W68yAGX/?lang=nl_NL",
"qr_url": "https://qrcode.ideal.nl/qrcode/15b6021c-0102-4ed2-84b3-4a99272179f7.png"
}
}- All parameters shown are required field(s)
| Parameter | Type | Description |
|---|---|---|
| type | string | Specifies the payment flow for the checkout process. Options: redirect, direct. |
| gateway | string | The unique gateway id to immediately direct the customer to the payment method. You retrieve these gateways using a gateway request. Options: iDEALQR. |
| order_id | string | The unique identifier from your system for the order. |
| currency | string | The currency (ISO-4217) you want the customer to pay with. |
| amount | integer | The amount (in cents) that the customer needs to pay. |
| description | string | A text which will be shown with the order in MultiSafepay Control. If the customer’s bank supports it this description will also be shown on the customer’s bank statement. Max. 200 characters. HTML is no longer supported. Use the ‘items’ or ‘shopping_cart’ objects for this. |
| payment_options | object | Contains the redirect_url, cancel_url and notification_url |
| customer | object | Contains personal information about the customer. |
| gateway_info | object | |
| qr_size: | integer | QR image size in pixels, default: 250 - Sizes are between 100 and 2000, if the value does not meet this rule, default is applied. |
| allow_multiple | boolean | With the allow multiple parameter you can specify if a single QR code should be able to be used more than just once. |
| allow_change_amount | boolean | With the allow_change_amount_parameter you can specify if a customer should be able to change the amount to pay. Often used for donations. |
| max_amount | string | With the max_amount you can specify what the maximum amount can be in case the allow_change_amount option is activated. This parameter is required when allow_change_amount is set. |
Please make sure you check out our dedicated documentation for iDEAL QR.
ING Home’Pay
POST - /orders
{
"type": "direct",
"order_id": "my-order-id-1",
"gateway": "INGHOME",
"currency": "EUR",
"amount": "1000",
"description": "Test Order Description",
"payment_options": {
"notification_url": "http://www.example.com/client/notification?type=notification",
"redirect_url": "http://www.example.com/client/notification?type=redirect",
"cancel_url": "http://www.example.com/client/notification?type=cancel",
"close_window": ""
},
"customer": {
"locale": "en_US"
}
}JSON Response
{
"success": true,
"data": {
"transaction_id": 260468043,
"order_id": "apitool_3401000",
"created": "2019-03-11T14:35:13",
"currency": "EUR",
"amount": 100000,
"description": "product description",
"var1": null,
"var2": null,
"var3": null,
"items": null,
"amount_refunded": 0,
"status": "initialized",
"financial_status": "initialized",
"reason": "",
"reason_code": "",
"fastcheckout": "NO",
"modified": "2019-03-11T14:35:13",
"customer": {
"locale": "en_US",
"first_name": null,
"last_name": null,
"address1": null,
"address2": null,
"house_number": null,
"zip_code": null,
"city": null,
"state": null,
"country": null,
"country_name": null,
"phone1": null,
"phone2": "",
"email": ""
},
"payment_details": {
"recurring_id": null,
"type": "INGHOME",
"account_id": "https://pay.multisafepay.com/direct/complete/",
"account_holder_name": null,
"external_transaction_id": 663302604477,
"account_iban": "66d2f141b864621139096d38ce80bc4eff4bb439"
},
"costs": [
{
"transaction_id": 279925866,
"description": "1 For ING HomePay Transactions",
"type": "SYSTEM",
"amount": 1
}
],
"payment_url": "https://homepay.ing.be/EN/index.jsp?RETURN_URL=https%3A%2F%2Fpay.multisafepay.com%2Fdirect%2Fcomplete%2F%3Fmspid%3D260468043&CURRENCY=EUR&AMOUNT=000000100000&RETURN_METHOD=GET&MESSAGE=663302604477&VERSION=2&VENDOR_ID=18204457201&HASH=66d2f141b864621139096d38ce80bc4eff4bb439"
}
}- All parameters shown are required field(s)
| Parameter | Type | Description |
|---|---|---|
| type | string | Specifies the payment flow for the checkout process. Options: direct, redirect, paymentlink. |
| gateway | string | The unique gateway id to immediately direct the customer to the payment method. You retrieve these gateways using a gateway request. Options: INGHOME. |
| order_id | string | The unique identifier from your system for the order. |
| currency | string | The currency ISO-4217 you want the customer to pay with. |
| amount | integer | The amount (in cents) that the customer needs to pay. |
| description | string | A text which will be shown with the order in MultiSafepay Control. If the customer’s bank supports it this description will also be shown on the customer’s bank statement. Max. 200 characters. HTML is no longer supported. Use the ‘items’ or ‘shopping_cart’ objects for this. |
| payment_options | object | Contains the redirect_url, cancel_url and notification_url |
| customer | object | Contains personal information about the customer. |
Please make sure you check out our dedicated documentation for ING Home’Pay.
KBC
POST - /orders
{
"type": "redirect",
"order_id": "my-order-id-1",
"gateway": "KBC",
"currency": "EUR",
"amount": "1000",
"description": "Test Order Description",
"payment_options": {
"notification_url": "http://www.example.com/client/notification?type=notification",
"redirect_url": "http://www.example.com/client/notification?type=redirect",
"cancel_url": "http://www.example.com/client/notification?type=cancel",
"close_window": ""
},
"customer": {
"locale": "en_US"
}
}JSON Response
{
"success": true,
"data": {
"order_id": "my-order-id-1",
"payment_url": "https://payv2.multisafepay.com/connect/13oElUaESR7YS2b4gUJV9oI4tUXeb1mj1D8/?lang=nl_NL"
}
}- All parameters shown are required field(s)
| Parameter | Type | Description |
|---|---|---|
| type | string | Specifies the payment flow for the checkout process. Options: direct, redirect, paymentlink. |
| gateway | string | The unique gateway id to immediately direct the customer to the payment method. You retrieve these gateways using a gateway request. Options: KBC. |
| order_id | string | The unique identifier from your system for the order. |
| currency | string | The currency (ISO-4217) you want the customer to pay with. |
| amount | integer | The amount (in cents) that the customer needs to pay. |
| description | string | A text which will be shown with the order in MultiSafepay Control. If the customer’s bank supports it this description will also be shown on the customer’s bank statement. Max. 200 characters. HTML is no longer supported. Use the ‘items’ or ‘shopping_cart’ objects for this. |
| payment_options | object | Contains the redirect_url, cancel_url and notification_url |
| customer | object | Contains personal information about the customer. |
Please make sure you check out our dedicated documentation for KBC.
Klarna
POST - /orders
{
"type": "direct",
"gateway": "KLARNA",
"order_id": "my-order-id-1",
"currency": "EUR",
"amount": "26000",
"description": "Test Order Description",
"var1": "",
"var2": "",
"var3": "",
"items": "",
"manual": "false",
"gateway_info": {
"birthday": "1970-07-10",
"gender": "male",
"phone": "0612345678",
"email": "[email protected]"
},
"payment_options": {
"notification_url": "http://www.example.com/client/notification?type=notification",
"redirect_url": "http://www.example.com/client/notification?type=redirect",
"cancel_url": "http://www.example.com/client/notification?type=cancel",
"close_window": ""
},
"customer": {
"locale": "en_US",
"ip_address": "31.148.195.10",
"forwarded_ip": "",
"first_name": "Testperson-nl",
"last_name": "Approved",
"address1": "Neherkade",
"address2": "",
"house_number": "39c",
"zip_code": "1033 SC",
"city": "Gravenhage",
"state": "",
"country": "NL",
"email": "[email protected]",
"referrer": "http://www.example.com",
"user_agent": "Mozilla/5.0 (Windows NT 6.3; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/38.0.2125.111 Safari/537.36"
},
"delivery": {
"first_name": "Testperson-nl",
"last_name": "Approved",
"address1": "Neherkade",
"address2": "",
"house_number": "39c",
"zip_code": "1033 SC",
"city": "Gravenhage",
"state": "",
"country": "NL",
"phone": "",
"email": ""
},
"shopping_cart": {
"items": [
{
"name": "Item demo 1",
"description": "",
"unit_price": "90",
"quantity": "2",
"merchant_item_id": "111111",
"tax_table_selector": "none",
"weight": {
"unit": "KG",
"value": "12"
}
},
{
"name": "Item demo 2",
"description": "",
"unit_price": "35",
"quantity": "2",
"merchant_item_id": "666666",
"tax_table_selector": "none",
"weight": {
"unit": "KG",
"value": "20"
}
},
{
"name": "Item shipping - Flat Rate - Fixed",
"description": "Shipping",
"unit_price": "10",
"quantity": "1",
"merchant_item_id": "msp-shipping",
"tax_table_selector": "none",
"weight": {
"unit": "KG",
"value": "0"
}
}
]
},
"checkout_options": {
"tax_tables": {
"default": {
"shipping_taxed": "true",
"rate": "0.21"
},
"alternate": [
{
"name": "BTW21",
"standalone": true,
"rules": [
{
"rate": "0.21"
}
]
},
{
"name": "BTW6",
"standalone": true,
"rules": [
{
"rate": "0.06"
}
]
},
{
"name": "BTW0",
"standalone": true,
"rules": [
{
"rate": "0.00"
}
]
},
{
"name": "0.0000",
"standalone": false,
"rules": [
{
"rate": "0"
}
]
},
{
"name": "0.0000",
"standalone": false,
"rules": [
{
"rate": "0"
}
]
},
{
"name": "FEE",
"standalone": false,
"rules": [
{
"rate": "0.00"
}
]
},
{
"name": "none",
"standalone": false,
"rules": [
{
"rate": "0.00"
}
]
},
{
"name": "2",
"standalone": true,
"rules": [
{
"rate": "0.0825",
"country": "US"
},
{
"rate": "0.08375",
"country": "NL"
}
]
}
]
}
}
}JSON Response
{
"success": true,
"data": {
"transaction_id": 2340676,
"order_id": "my-order-id-1",
"created": "2017-09-29T16:13:10",
"currency": "EUR",
"amount": 26000,
"description": "Test Order Description",
"var1": null,
"var2": null,
"var3": null,
"items": "",
"amount_refunded": 0,
"status": "completed",
"financial_status": "initialized",
"reason": "",
"reason_code": "",
"fastcheckout": "NO",
"modified": "2017-09-29T16:13:10",
"customer": {
"locale": "en_US",
"first_name": "Testperson-nl",
"last_name": "Approved",
"address1": "Neherkade",
"address2": null,
"house_number": "39c",
"zip_code": "1033SC",
"city": "Gravenhage",
"state": null,
"country": "NL",
"country_name": null,
"phone1": "0612345678",
"phone2": "",
"email": "[email protected]"
},
"payment_details": {
"recurring_id": null,
"type": "",
"account_id": 10071970,
"account_holder_name": null,
"external_transaction_id": 2379429850
},
"shopping_cart": {
"items": [
{
"name": "Item demo 1",
"description": "",
"unit_price": "90.00",
"currency": "EUR",
"quantity": 2,
"merchant_item_id": 666666,
"tax_table_selector": "none",
"cashback": "",
"image": "",
"product_url": "",
"weight": {
"unit": "KG",
"value": 12
},
"options": []
},
{
"name": "Item demo 2",
"description": "",
"unit_price": "35.00",
"currency": "EUR",
"quantity": 2,
"merchant_item_id": 666666,
"tax_table_selector": "none",
"cashback": "",
"image": "",
"product_url": "",
"weight": {
"unit": "KG",
"value": 20
},
"options": []
},
{
"name": "Item shipping - Flat Rate - Fixed",
"description": "Shipping",
"unit_price": "10.00",
"currency": "EUR",
"quantity": 1,
"merchant_item_id": "msp-shipping",
"tax_table_selector": "none",
"cashback": "",
"image": "",
"product_url": "",
"weight": {
"unit": "KG",
"value": 0
},
"options": []
}
]
},
"checkout_options": {
"default": {
"shipping_taxed": true,
"rate": 0.21
},
"alternate": [
{
"standalone": true,
"name": "BTW21",
"rules": [
{
"rate": 0.21,
"country": ""
}
]
},
{
"standalone": true,
"name": "BTW6",
"rules": [
{
"rate": 0.06,
"country": ""
}
]
},
{
"standalone": true,
"name": "BTW0",
"rules": [
{
"rate": "0.00",
"country": ""
}
]
},
{
"standalone": "",
"name": "0.0000",
"rules": [
{
"rate": "0.00",
"country": ""
}
]
},
{
"standalone": "",
"name": "0.0000",
"rules": [
{
"rate": "0.00",
"country": ""
}
]
},
{
"standalone": "",
"name": "FEE",
"rules": [
{
"rate": "0.00",
"country": ""
}
]
},
{
"standalone": "",
"name": "none",
"rules": [
{
"rate": "0.00",
"country": ""
}
]
},
{
"standalone": true,
"name": 2,
"rules": [
{
"rate": 0.0825,
"country": "US"
},
{
"rate": 0.08375,
"country": "NL"
}
]
}
]
},
"order_adjustment": {
"total_adjustment": "0.00",
"total_tax": "0.00"
},
"order_total": "260.00",
"costs": [],
"payment_url": "http://www.example.com/client/?action=notification&type=redirect&transactionid=2340676",
"cancel_url": "http://www.example.com/client/?action=notification&type=cancel&transactionid=2340676"
}
}Creates a Klarna order to be paid after delivery
- All parameters shown are required field(s)
| Parameter | Type | Description |
|---|---|---|
| type | string | Specifies the payment flow for the checkout process. Options: direct, redirect. |
| gateway | string | The unique gateway_id to immediately direct the customer to the payment method. You retrieve these gateways using a gateway request. Options: KLARNA. |
| order_id | string | The unique identifier from your system for the order. |
| currency | string | The currency ISO-4217 you want the customer to pay with. |
| amount | integer | The amount (in cents) that the customer needs to pay. |
| description | string | A text which will be shown with the order in MultiSafepay Control. If the customer’s bank supports it this description will also be shown on the customer’s bank statement. Max. 200 characters. HTML is no longer supported. Use the ‘items’ or ‘shopping_cart’ objects for this. |
| payment_options | object | Contains the redirect_url, cancel_url and notification_url |
| customer | object | Contains personal information about the customer. Values for first_name and last_name require minimum two characters. |
| delivery | object | Contains the delivery information for the shipment. Values for first_name and last_name require minimum two characters. |
| shopping_cart | object | Contains all purchased items including tax class. |
| checkout_options | object | Contains the definitions for the VAT class. |
| gateway_info | object | Contains the issuer_id. |
| birthday | string | The birth date of the customer in the format yyyy-mm-dd. This is required for credit checks. (Required for Klarna & Pay After Delivery, optional for E-Invoicing on request). |
| phone | string | The phone number where the customer can be reached. This is required for credit checks and to contact the customer in case of non-payment. |
| string | The email address where the system can send payment instructions to the customer. | |
| gender | string | The gender of the customer. (Required for Klarna, optional for Pay After Delivery and E-Invoicing) Options: male, female. |
| ip_address | string | The IP address of the customer. “Required” with post payment and credit card payment methods. Due to validation of the customer IP address, we need to receive the actual IP address of the end user within the ip_address field. More info |
| forwarded_ip: | string | The X-FORWARDED-FOR header of the customer request when using a proxy. More info |
Please note that first_name and last_name in both customer and delivery objects require minimum two characters per entry. Failing to do so might result in unexpected errors. Given the nature of this payment method, we recommend you to always require full names (not initials, abbreviations, acronyms).
Make sure you check out our dedicated documentation for Klarna.
Pay After Delivery
POST - /orders
{
"type": "redirect",
"gateway": "PAYAFTER",
"order_id": "my-order-id-1",
"currency": "EUR",
"amount": "26000",
"description": "Test Order Description",
"var1": "",
"var2": "",
"var3": "",
"items": "",
"manual": "false",
"gateway_info": {
"birthday": "1980-01-30",
"bankaccount": "0417164300",
"phone": "0208500500",
"email": "[email protected]"
},
"payment_options": {
"notification_url": "http://www.example.com/client/notification?type=notification",
"redirect_url": "http://www.example.com/client/notification?type=redirect",
"cancel_url": "http://www.example.com/client/notification?type=cancel",
"close_window": ""
},
"customer": {
"locale": "us",
"ip_address": "31.148.195.10",
"forwarded_ip": "",
"first_name": "Testperson-nl",
"last_name": "Approved",
"address1": "Neherkade",
"address2": "",
"house_number": "39c",
"zip_code": "1033 SC",
"city": "Gravenhage",
"state": "",
"country": "NL",
"email": "[email protected]",
"referrer": "http://www.example.com",
"user_agent": "Mozilla/5.0 (Windows NT 6.3; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/38.0.2125.111 Safari/537.36"
},
"delivery": {
"first_name": "Testperson-nl",
"last_name": "Approved",
"address1": "Neherkade",
"address2": "",
"house_number": "39c",
"zip_code": "1033 SC",
"city": "Gravenhage",
"state": "",
"country": "NL",
"phone": "",
"email": ""
},
"shopping_cart": {
"items": [
{
"name": "Item demo 1",
"description": "",
"unit_price": "90",
"quantity": "2",
"merchant_item_id": "111111",
"tax_table_selector": "none",
"weight": {
"unit": "KG",
"value": "12"
}
},
{
"name": "Item demo 2",
"description": "",
"unit_price": "35",
"quantity": "2",
"merchant_item_id": "666666",
"tax_table_selector": "none",
"weight": {
"unit": "KG",
"value": "20"
}
},
{
"name": "Item shipping - Flat Rate - Fixed",
"description": "Shipping",
"unit_price": "10",
"quantity": "1",
"merchant_item_id": "msp-shipping",
"tax_table_selector": "none",
"weight": {
"unit": "KG",
"value": "0"
}
}
]
},
"checkout_options": {
"tax_tables": {
"default": {
"shipping_taxed": "true",
"rate": "0.21"
},
"alternate": [
{
"name": "BTW21",
"standalone": true,
"rules": [
{
"rate": "0.21"
}
]
},
{
"name": "BTW6",
"standalone": true,
"rules": [
{
"rate": "0.06"
}
]
},
{
"name": "BTW0",
"standalone": true,
"rules": [
{
"rate": "0.00"
}
]
},
{
"name": "0.0000",
"standalone": false,
"rules": [
{
"rate": "0"
}
]
},
{
"name": "0.0000",
"standalone": false,
"rules": [
{
"rate": "0"
}
]
},
{
"name": "FEE",
"standalone": false,
"rules": [
{
"rate": "0.00"
}
]
},
{
"name": "none",
"standalone": false,
"rules": [
{
"rate": "0.00"
}
]
},
{
"name": "2",
"standalone": true,
"rules": [
{
"rate": "0.0825",
"country": "US"
},
{
"rate": "0.08375",
"country": "NL"
}
]
}
]
}
}
}JSON Response
{
"success": true,
"data": {
"transaction_id": 2340676,
"order_id": "my-order-id-1",
"created": "2017-09-29T16:13:10",
"currency": "EUR",
"amount": 26000,
"description": "Test Order Description",
"var1": null,
"var2": null,
"var3": null,
"items": "",
"amount_refunded": 0,
"status": "completed",
"financial_status": "initialized",
"reason": "",
"reason_code": "",
"fastcheckout": "NO",
"modified": "2017-09-29T16:13:10",
"customer": {
"locale": "en_US",
"first_name": "Testperson-nl",
"last_name": "Approved",
"address1": "Neherkade",
"address2": null,
"house_number": "39c",
"zip_code": "1033SC",
"city": "Gravenhage",
"state": null,
"country": "NL",
"country_name": null,
"phone1": "0612345678",
"phone2": "",
"email": "[email protected]"
},
"payment_details": {
"recurring_id": null,
"type": "",
"account_id": 10071970,
"account_holder_name": null,
"external_transaction_id": 2379429850
},
"shopping_cart": {
"items": [
{
"name": "Item demo 1",
"description": "",
"unit_price": "90.00",
"currency": "EUR",
"quantity": 2,
"merchant_item_id": 666666,
"tax_table_selector": "none",
"cashback": "",
"image": "",
"product_url": "",
"weight": {
"unit": "KG",
"value": 12
},
"options": []
},
{
"name": "Item demo 2",
"description": "",
"unit_price": "35.00",
"currency": "EUR",
"quantity": 2,
"merchant_item_id": 666666,
"tax_table_selector": "none",
"cashback": "",
"image": "",
"product_url": "",
"weight": {
"unit": "KG",
"value": 20
},
"options": []
},
{
"name": "Item shipping - Flat Rate - Fixed",
"description": "Shipping",
"unit_price": "10.00",
"currency": "EUR",
"quantity": 1,
"merchant_item_id": "msp-shipping",
"tax_table_selector": "none",
"cashback": "",
"image": "",
"product_url": "",
"weight": {
"unit": "KG",
"value": 0
},
"options": []
}
]
},
"checkout_options": {
"default": {
"shipping_taxed": true,
"rate": 0.21
},
"alternate": [
{
"standalone": true,
"name": "BTW21",
"rules": [
{
"rate": 0.21,
"country": ""
}
]
},
{
"standalone": true,
"name": "BTW6",
"rules": [
{
"rate": 0.06,
"country": ""
}
]
},
{
"standalone": true,
"name": "BTW0",
"rules": [
{
"rate": "0.00",
"country": ""
}
]
},
{
"standalone": "",
"name": "0.0000",
"rules": [
{
"rate": "0.00",
"country": ""
}
]
},
{
"standalone": "",
"name": "0.0000",
"rules": [
{
"rate": "0.00",
"country": ""
}
]
},
{
"standalone": "",
"name": "FEE",
"rules": [
{
"rate": "0.00",
"country": ""
}
]
},
{
"standalone": "",
"name": "none",
"rules": [
{
"rate": "0.00",
"country": ""
}
]
},
{
"standalone": true,
"name": 2,
"rules": [
{
"rate": 0.0825,
"country": "US"
},
{
"rate": 0.08375,
"country": "NL"
}
]
}
]
},
"order_adjustment": {
"total_adjustment": "0.00",
"total_tax": "0.00"
},
"order_total": "260.00",
"costs": [],
"payment_url": "http://www.example.com/client/?action=notification&type=redirect&transactionid=2340676",
"cancel_url": "http://www.example.com/client/?action=notification&type=cancel&transactionid=2340676"
}
}Creates a Pay After Delivery order.
- All parameters shown are required field(s)
| Parameter | Type | Description |
|---|---|---|
| type | string | Specifies the payment flow for the checkout process. Options: direct, redirect. |
| gateway | string | The unique gateway id to immediately direct the customer to the payment method. You retrieve these gateways using a gateway request. Option: PAYAFTER. |
| order_id | string | The unique identifier from your system for the order. |
| currency | string | The currency (ISO-4217) you want the customer to pay with. |
| amount | integer | The amount (in cents) that the customer needs to pay. |
| description | string | A text which will be shown with the order in MultiSafepay Control. If the customer’s bank supports it this will also be shown on the bank statement. Max 200 characters. HTML is no longer supported. Use the required ‘shopping-cart’ object for this. |
| payment_options | object | Contains the redirect_url, cancel_url and notification_url |
| custom_info | object | custom_info is a ‘placeholder’ where the merchant can input specific data related to the transaction |
| customer | object | Contains the personal information of the customer. Values for first_name and last_name require minimum two characters. |
| delivery | object | Contains the delivery information for the shipment. Values for first_name and last_name require minimum two characters. |
| shopping_cart | object | Contains all purchased items including tax class. |
| checkout_options | object | Defines all tax classes to be used for the shopping cart items. |
| gateway_info | object | Defines certain customer data (issuer_id) needed for the credit check. |
| birthday | string | The birth date of the customer in the format yyyy-mm-dd. This is required for credit checks. (Required for Klarna & Pay After Delivery, optional for E-Invoicing on request). |
| bank_account | string | The formatted IBAN for the customer. This is required for credit checks. (Required for Pay After Delivery). |
| phone | string | The phone number where the customer can be reached. This is required for credit checks and to contact the customer in case of non-payment. |
| string | The email address where the system can send payment instructions to the customer. | |
| ip_address | string | The IP address of the customer. “Required” with post payment and credit card payment methods. Due to validation of the customer IP address, we need to receive the actual IP address of the end user within the ip_address field. More info |
| forwarded_ip | string | The X-FORWARDED-FOR header of the customer request when using a proxy. More info |
Please note that first_name and last_name in both customer and delivery objects require minimum two characters per entry. Failing to do so might result in unexpected errors. Given the nature of this payment method, we recommend you to always require full names (not initials, abbreviations, acronyms).
Make sure you check out our dedicated documentation for Pay After Delivery.
PayPal
POST - /orders
{
"type": "redirect",
"order_id": "my-order-id-1",
"gateway": "PAYPAL",
"currency": "EUR",
"amount": "1000",
"description": "Test Order Description",
"payment_options": {
"notification_url": "http://www.example.com/client/notification?type=notification",
"redirect_url": "http://www.example.com/client/notification?type=redirect",
"cancel_url": "http://www.example.com/client/notification?type=cancel",
"close_window": ""
},
"customer": {
"locale": "en_US"
}
}JSON Response
{
"success": true,
"data": {
"order_id": "my-order-id-1",
"payment_url": "https://payv2.multisafepay.com/connect/13oElUaESR7YS2b4gUJV9oI4tUXeb1mj1D8/?lang=nl_NL"
}
}- All parameters shown are required field(s)
| Parameter | Type | Description |
|---|---|---|
| type | string | Specifies the payment flow for the checkout process. Options: direct, redirect, checkout, paymentlink. |
| gateway | string | The unique gateway id to immediately direct the customer to the payment method. You retrieve these gateways using a gateway request. Option: PAYPAL. |
| order_id: | string | The unique identifier from your system for the order. |
| currency: | string | The currency (ISO-4217) you want the customer to pay with. |
| amount: | integer | The amount (in cents) that the customer needs to pay. |
| description: | string | A text which will be shown with the order in MultiSafepay Control. If the customer’s bank supports it this will also be shown on the customer’s bank statement. Max. 200 characters. HTML is no longer supported. Use the ‘items’or ‘shopping_cart’ objects for this. |
| payment_options: | object | Contains the redirect_url, cancel_url and notification_url |
| customer | object | Contains the personal information of the customer. |
Please make sure you check out our dedicated documentation for PayPal.
Santander Betaalplan
POST - /orders
{
"type": "direct",
"order_id": "my-order-id-1",
"gateway": "SANTANDER",
"currency": "EUR",
"amount": 50000,
"description": "Test Order Description",
"payment_options": {
"notification_url": "http://www.example.com/client/notification?type=notification",
"redirect_url": "http://www.example.com/client/notification?type=redirect",
"cancel_url": "http://www.example.com/client/notification?type=cancel",
"close_window": ""
},
"customer": {
"locale": "en_US",
"ip_address": "31.148.195.10",
"forwarded_ip": "",
"first_name": "John",
"last_name": "Doe",
"address1": "Neherkade",
"house_number": "XI",
"zip_code": "2521VA",
"city": "Gravenhage",
"state": "",
"country": "NL",
"email": "[email protected]",
"referrer": "http://example.com",
"user_agent": "Mozilla//5.0 (Windows NT 6.3; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/38.0.2125.111 Safari/537.36"
},
"gateway_info": {
"birthday": "1970-07-10",
"gender": "male",
"phone": "0612345678",
"email": "[email protected]"
}
}JSON Response
{
"success": true,
"data": {
"transaction_id": 2333720,
"order_id": "my-order-id-1",
"created": "2017-08-07T10:07:07",
"currency": "EUR",
"amount": 100000,
"description": "product description",
"var1": null,
"var2": null,
"var3": null,
"items": null,
"amount_refunded": 0,
"status": "initialized",
"financial_status": "initialized",
"reason": "",
"reason_code": "",
"fastcheckout": "NO",
"modified": "2017-08-07T10:07:07",
"customer": {
"locale": "en_US",
"first_name": null,
"last_name": null,
"address1": null,
"address2": null,
"house_number": null,
"zip_code": null,
"city": null,
"state": null,
"country": null,
"country_name": null,
"phone1": null,
"phone2": "",
"email": ""
},
"payment_details": {
"recurring_id": null,
"type": "SANTANDER",
"account_id": null,
"account_holder_name": null,
"external_transaction_id": null
},
"costs": [
{
"transaction_id": 406933,
"description": "Cost Description",
"type": "SYSTEM",
"amount": 0.49
}
],
"payment_url": "https://retailersowtest.santander.nl/EDurables/Home.aspx?guid=XXXXX"
}
}- All parameters shown are required field(s)
| Parameter | Type | Description |
|---|---|---|
| type | string | Specifies the payment flow for the checkout process. Options: direct, redirect, paymentlink. |
| gateway | string | The unique gateway id to immediately direct the customer to the payment method. You retrieve these gateways using a gateway request. Options: SANTANDER. |
| order_id | string | The unique identifier from your system for the order. |
| currency | string | The currency (ISO-4217) you want the customer to pay with. |
| amount | integer | The amount (in cents) that the customer needs to pay. In this case minimum 30000. |
| description | string | A text which will be shown with the order in MultiSafepay Control. If the customer’s bank supports it this description will also be shown on the bank statement. Max. 200 characters. HTML is no longer supported. Use the ‘items’ or ‘shopping cart’ objects for this. |
| payment_options | object | Contains the redirect_url, cancel_url and notification_url |
| customer | object | Contains the personal information of the customer. Values for first_name and last_name require minimum two characters. |
| gateway_info | object | Contains the information of the customer needed for the credit check. |
| ip_address | string | The IP address of the customer. “Required” with post payment and credit card payment methods. Due to validation of the customer IP address, we need to receive the actual IP address of the end user within the ip_address field. More info |
| forwarded_ip | string | The X-FORWARDED-FOR header of the customer request when using a proxy. More info |
Please note that first_name and last_name in the customer object requires minimum two characters per entry. Failing to do so might result in unexpected errors. Given the nature of this payment method, we recommend you to always require full names (not initials, abbreviations, acronyms).
Make sure you check out our dedicated documentation for Betaalplan.
SOFORT
POST - /orders
{
"type": "direct",
"order_id": "my-order-id-1",
"gateway": "DIRECTBANK",
"currency": "EUR",
"amount": "1000",
"description": "Test Order Description",
"payment_options": {
"notification_url": "http://www.example.com/client/notification?type=notification",
"redirect_url": "http://www.example.com/client/notification?type=redirect",
"cancel_url": "http://www.example.com/client/notification?type=cancel",
"close_window": ""
},
"customer": {
"locale": "en_US"
}
}JSON Response
{
"success": true,
"data": {
"order_id": "my-order-id-1",
"payment_url": "https://payv2.multisafepay.com/connect/13oElUaESR7YS2b4gUJV9oI4tUXeb1mj1D8/?lang=nl_NL"
}
}- All parameters shown are required field(s)
| Parameter | Type | Description |
|---|---|---|
| type | string | Specifies the payment flow for the checkout process. Options: redirect. |
| gateway | string | The unique gateway id to immediately direct the customer to the payment method. You retrieve these gateways using a gateway request. Option: DIRECTBANK. |
| order_id: | string | The unique identifier from your system for the order. |
| currency: | string | The currency (ISO-4217) you want the customer to pay with. |
| amount: | integer | The amount (in cents) that the customer needs to pay. |
| description: | string | A text which will be shown with the order in MultiSafepay Control. If the customer’s bank supports it this will also be shown on the bank statement. Max. 200 characters. HTML is no longer supported. Use the ‘items’ or ‘shopping_cart’ objects for this. |
| payment_options: | object | Contains the redirect_url, cancel_url and notification_url |
| customer | object | Contains personal information about the customer. |
Please make sure you check out our dedicated documentation for SOFORT Banking.
Trustly
POST - /orders
{
"type": "redirect",
"order_id": "my-order-id-1",
"currency": "EUR",
"amount": 1000,
"gateway": "TRUSTLY",
"description": "Test Order Description",
"custom_info": {},
"payment_options": {
"notification_url": "http://www.example.com/client/notification?type=notification",
"redirect_url": "http://www.example.com/client/notification?type=redirect",
"cancel_url": "http://www.example.com/client/notification?type=cancel",
"close_window": ""
},
"customer": {
"first_name": "Testperson-nl",
"last_name": "Approved",
"country": "NL",
"email": "[email protected]"
}
}JSON Response
{
"success": true,
"data": {
"order_id": "my-order-id-1",
"payment_url": "https://payv2.multisafepay.com/connect/13oElUaESR7YS2b4gUJV9oI4tUXeb1mj1D8/?lang=nl_NL"
}
}- All parameters shown are required field(s)
| Parameter | Type | Description |
|---|---|---|
| type | string | Specifies the payment flow for the checkout process. Options: redirect, direct, paymentlink. |
| gateway | string | The unique gateway_id to immediately direct the customer to the payment method. You retrieve these gateways using a gateway request. Option: TRUSTLY. |
| order_id | string | The unique identifier from your system for the order. |
| currency | string | The currency (ISO-4217) you want the customer to pay with. |
| amount | integer | The amount (in cents) that the customer needs to pay. |
| description | string | A text which will be shown with the order in MultiSafepay Control. If the customer’s bank supports it this will also be shown on the bank statement. Max. 200 character. HTML is no longer supported. Use the ‘items’ or ‘shopping_cart’ objects for this. |
| payment_options | object | |
| notification_url | string | Endpoint where we will send the notifications to notification_url |
| redirect_url | string | Customer will be redirected to this page after a successful payment. |
| cancel_url | string | Customer will be redirected to this page after a failed payment. |
| customer | object | Contains the personal information of the customer. |
Please make sure you check out our dedicated documentation for Trustly.
TrustPay
POST - /orders
{
"type": "redirect",
"order_id": "my-order-id-1",
"currency": "CZK",
"amount": 1000,
"gateway": "",
"description": "Test Order Description",
"custom_info": {},
"payment_options": {
"notification_url": "http://www.example.com/client/notification?type=notification",
"redirect_url": "http://www.example.com/client/notification?type=redirect",
"cancel_url": "http://www.example.com/client/notification?type=cancel",
"close_window": ""
},
"customer": {
"first_name": "Testperson-nl",
"last_name": "Approved",
"country": "CZ",
"email": "[email protected]"
}
}JSON Response
{
"success": true,
"data": {
"order_id": "my-order-id-1",
"payment_url": "https://payv2.multisafepay.com/connect/13oElUaESR7YS2b4gUJV9oI4tUXeb1mj1D8/?lang=en_CZ"
}
}- All parameters shown are required field(s)
| Parameter | Type | Description |
|---|---|---|
| type | string | Specifies the payment flow for the checkout process. Options: redirect. |
| gateway | string | The unique gateway_id to immediately direct the customer to the payment method. You retrieve these gateways using a gateway request. |
| order_id | string | The unique identifier from your system for the order. |
| currency | string | The currency (ISO-4217) you want the customer to pay with. The payment method only processes the currency Czech koruna (CZK). |
| amount | integer | The amount (in cents) that the customer needs to pay. |
| description | string | A text which will be shown with the order in MultiSafepay Control. If the customer’s bank supports it this will also be shown on the bank statement. Max. 200 character. HTML is no longer supported. Use the ‘items’ or ‘shopping_cart’ objects for this. |
| payment_options | object | |
| notification_url | string | Endpoint where we will send the notifications to notification_url |
| redirect_url | string | Customer will be redirected to this page after a successful payment. |
| cancel_url | string | Customer will be redirected to this page after a failed payment. |
| customer | object | |
| first_name | string | The customer’s first name. |
| last_name | string | The customer’s last name. |
| country | string | Customer’s provided country code ISO 3166-1 |
| string | Customer’s provided email address. Used to send Second Chance emails, in fraud checks and the sending bank transfer email. |
Please make sure you check out our dedicated documentation for TrustPay.
Branded credit card
POST - /order
{
"type": "redirect",
"order_id": "my-order-id-1",
"gateway": "VISA",
"currency": "EUR",
"amount": "1000",
"description": "Test Order Description",
"payment_options": {
"notification_url": "http://www.example.com/client/notification?type=notification",
"redirect_url": "http://www.example.com/client/notification?type=redirect",
"cancel_url": "http://www.example.com/client/notification?type=cancel",
"close_window": ""
},
"customer": {
"locale": "it_IT",
"ip_address": "31.148.195.10"
}
}JSON Response
{
"success": true,
"data": {
"order_id": "My-order-id-1",
"payment_url": "https://payv2.multisafepay.com/connect/99wi0OTuiCaTY2nwEiEOybWpVx8MNwrJ75c/?lang=it_IT"
}
}- All parameters shown are required field(s)
| Parameter | Type | Description |
|---|---|---|
| type | string | Specifies the payment flow for the checkout process. Options: redirect. |
| gateway | string | The unique gateway id to immediately direct the customer to the payment method. You retrieve these gateways using a gateway request. Options: CREDITCARD, VISA and MASTERCARD. |
| order_id | string | The unique identifier from your system for the order. |
| currency | string | The currency ISO-4217 you want the customer to pay with. |
| amount | integer | The amount (in cents) that the customer needs to pay. |
| description | string | A text which will be shown with the order in MultiSafepay Control. If the customer’s bank supports it this will also be shown on the bank statement. Max. 200 characters. HTML is no longer supported. Use the ‘items’ or ‘shopping_cart’ objects for this. |
| payment_options | object | |
| notification_url | string | Endpoint where we will send the notifications to. notification_url |
| redirect_url | string | Customer will be redirected to this page after a successful payment. |
| cancel_url | string | Customer will be redirected to this page after a failed payment. |
| customer | object | |
| locale | string | Displays the correct language and payment methods on the payment page. It also has an influence on sending the set email templates. Use the format ab_CD with ISO 639 language codes and ISO 3166 country codes. Default: en_US. |
| ip_address | string | The IP address of the customer. “Required” with post payment and credit card payment methods. Due to validation of the customer IP address, we need to receive the actual IP address of the end user within the ip_address field. More info |
The desired logo of a branded credit card will only be shown if the locale is correctly supplied in a transaction request.
Please make sure to check out our dedicated documentation on CartaSi, Carte Bleue, Dankort and Postepay.
CartaSi and Postepay
"customer": {
"locale": "it_IT Dankort
"customer": {
"locale": "da_DK"Carte Bleue
"customer": {
"locale": "fr_FR"Transactions
Create a refund
POST - /orders/{order_id}/refunds
{
"currency": "EUR",
"amount": "8",
"description": "Your refund description"
}JSON Response
{
"success": true,
"data": {
"transaction_id": 3326965,
"refund_id": 3326969
}
}Total or partial refund of an order
| Parameter | Type | Description |
|---|---|---|
| id | string | The unique identifier of the order. |
| currency | string | The currency to process the refund in. This must be the same as the original transaction. |
| amount | integer | The amount (in cents) to be refunded. Please be aware that an amount of 0 (zero) will trigger a full refund! This can be used the current balance of an transaction is unknown. |
| description | string | A description to be displayed with the transaction in MultiSafepay Control. If supported by the customers bank this description will be displayed on the customers bank statement. |
Refund with shopping cart
POST - /orders/{order_id}/refunds
{
"checkout_data": {
"items": [
{
"name": "Geometric Candle Holders",
"description": "",
"unit_price": "90",
"quantity": "3",
"merchant_item_id": "111111",
"tax_table_selector": "none",
"weight": {
"unit": "KG",
"value": "12"
}
},
{
"name": "Geometric Candle Holders",
"description": "",
"unit_price": "90",
"quantity": "-2",
"merchant_item_id": "111111",
"tax_table_selector": "none",
"weight": {
"unit": "KG",
"value": "12"
}
},
{
"name": "Nice apple",
"description": "",
"unit_price": "35",
"quantity": "1",
"merchant_item_id": "666666",
"tax_table_selector": "none",
"weight": {
"unit": "KG",
"value": "20"
}
},
{
"name": "Flat Rat - Fixed",
"description": "Shipping",
"unit_price": "10",
"quantity": "1",
"merchant_item_id": "msp-shipping",
"tax_table_selector": "none",
"weight": {
"unit": "KG",
"value": "0"
}
}
]
}
}This request is used for creating a refund in orders with shopping cart like Pay After Delivery, E-Invoicing, Klarna and AfterPay.
To proceed with a refund:
- A request should be done to GET - /orders/{id} to obtain the cart items of the order and possible refunded items
- Add/remove items in the refund. In Klarna, refunds are done adding a “copy” of the item to refund, with negative “unit_price”, all others should set negative “quantity”.
- Please make sure that all data in the items match with the original transaction (except for the quantity/unit_price): In the example, two out of three ‘Geometric Candle Holders’ were refunded. Please note that the exact same ‘merchant_item_id’, ‘tax_table_selector’ and ‘unit_price’ were provided.
| Parameter | Type | Description |
|---|---|---|
| checkout_data | object | Contains the original shopping cart + copied items to be refunded. |
Other Requests
Categories
GET - /categories
JSON Response
{
"success": true,
"data": [
{
"code": 999,
"description": "Adult"
},
{
"code": 106,
"description": "Child and toys"
}
]
}Returns a list of website categories.
Chargeback
POST - /orders/{order_id}/files
{
"type": "",
"base64": "",
"description": "",
"name": ""
}JSON Response
{
"success": true,
"data": {
}
}MultiSafepay can challenge the chargeback on your behalf, but to do so, we need documented proof of the order. Upload files / documents via an API request.
We will be changing the process for handling chargebacks through the API in Q3 2019. Please contact your account manager or contact us at [email protected] for more information.
For more information about chargebacks, please refer to our dedicated page.
| Parameter | Type | Description |
|---|---|---|
| type | string | Specifies the payment flow for the checkout process. Options: chargeback. |
| base64 | string | Binary Base 64 encoded. Upload images “pdf, jpeg and png”. |
| description | string | Description or comments of the submitted file. |
| name | string | Name of the file. |
Reference
customer, object
"locale": "nl_NL",| Parameter | Type | Description |
|---|---|---|
| locale | string | Displays the correct language and payment methods on the payment page. It also has an influence on sending the set email templates. Use the format ab_CD with ISO 639 language codes and ISO 3166 country codes. Default: en_US. |
"ip_address": "31.148.195.10",| Parameter | Type | Description |
|---|---|---|
| ip_address | string | The IP address of the customer. “Required” with post payment and credit card payment methods. Due to validation of the customer IP address, we need to receive the actual IP address of the end user within the ip_address field. More info |
"forwarded_ip": "",| Parameter | Type | Description |
|---|---|---|
| forwarded_ip | string | The X-FORWARDED-FOR header of the customer request when using a proxy. More info |
"first_name": "customer's first name",| Parameter | Type | Description |
|---|---|---|
| first_name | string | The customer’s first name. |
"last_name": "customer's last name",| Parameter | Type | Description |
|---|---|---|
| last_name | string | The customer’s last name. |
"address1": "Kraanspoor",| Parameter | Type | Description |
|---|---|---|
| address1 | string | First line of customer’s provided address. |
"address2": "customer's address",| Parameter | Type | Description |
|---|---|---|
| address2 | string | Second line of customer’s provided address. |
"house_number": "39",| Parameter | Type | Description |
|---|---|---|
| house_number | string | Customer’s provided house number. |
"zip_code": "1033SC",| Parameter | Type | Description |
|---|---|---|
| zip_code | string | Customer’s provided zip / postal code. |
"city": "Amsterdam",| Parameter | Type | Description |
|---|---|---|
| city | string | Customer’s provided city. |
"country": "Netherlands",| Parameter | Type | Description |
|---|---|---|
| country | string | Customer’s provided country code ISO 3166-1 |
"phone": "0208500500",| Parameter | Type | Description |
|---|---|---|
| phone | string | Customer’s provided phone number. |
"email": "[email protected]",| Parameter | Type | Description |
|---|---|---|
| string | Customer’s provided email address. Used to send Second Chance emails and in fraud checks. |
days_active / seconds_active
The days or seconds active indicates the lifetime of a payment link.
The full documentation can be found on our FAQ page, The lifetime of a payment link.
"days_active": 30,| Parameter | Type | Description |
|---|---|---|
| days_active | string | The number of days the payment link will be active for. Default is 30. |
"seconds_active": 60,| Parameter | Type | Description |
|---|---|---|
| seconds_active | string | The number of seconds the payment link will be active for. Default is 30 days. |
payment_option, object
"notification_url": "http://www.example.com/client/notification?type=notification",| Parameter | Type | Description |
|---|---|---|
| notification_url | string | Endpoint where we will send the notifications to. notification_url |
"redirect_url": "http://www.example.com/client/notification?type=redirect",| Parameter | Type | Description |
|---|---|---|
| redirect_url | string | Customer will be redirected to this page after a successful payment. |
"cancel_url": "http://www.example.com/client/notification?type=cancel", | Parameter | Type | Description |
|---|---|---|
| cancel_url | string | Customer will be redirected to this page after a failed payment. |
"notification_method": "POST",| Parameter | Type | Description |
|---|---|---|
| notification_method | string | Enables push notifications (POST,GET) default: GET. |
"close_window": "true",| Parameter | Type | Description |
|---|---|---|
| close_window | bool | true, false. |
Transaction Statuses
Transactions can have the following statuses:
| Status | Name | Description |
|---|---|---|
| completed | Completed | Payment has been successfully completed and payout is guaranteed. Proceed with fulfillment. |
| initialized | Initialized | A payment link has been generated, but no payment has been received yet. |
| declined | Declined | Rejected by the the issuing bank. Read more about the reason why the transaction is declined in what does it mean |
| cancelled | Cancelled | Cancelled by the merchant (only applies to the status Initialized, Uncleared or Reserved). |
| void | Void | Cancelled by the merchant. |
| expired | Expired | Depending on the payment method unfinished transactions will close automatically after a predefined period. |
| uncleared | Uncleared | Waiting for manual permission of the merchant to approve/disapprove the payment. Read more on accepting uncleared credit card payments, how and why? |
| refunded | Refunded | Payment has been refunded (in full) to the customer. |
| partial_refunded | Partial Refunded | Payment has been partially refunded to the customer. |
| reserved | Reserved | Payout/refund has been put on reserved, a temporary status, until the merchant’s account has been checked on sufficient balance. |
| chargedback | Chargedback | Forced reversal of funds initiated by customer’s bank (issuer). Only applicable to Direct Debit and credit card payments. |
| shipped | Shipped | Order for payment has been set to shipped to mark the order as fulfilled and capture the money. |
Partners
Create a merchant account
POST - /partners
{
"product": "connect300",
"company_name": "Company name Partner",
"address1": "Kraanspoor",
"address2": "",
"zip_code": "1033SC",
"city": "Amsterdam",
"email": "",
"country": "NL",
"phone": "0205800500",
"password": "test123",
"address_apartment": "",
"software_partner": "Anders",
"partner": {
"api_user": "partner-account-user-name",
"api_pass": "partner-account-password"
},
"contact_details": {
"title": "Mr",
"name": "your name"
},
"bank_details": {
"account_number": "0123456789",
"bank_name": "Rabobank",
"country": "NL"
}
}JSON Response
{
"success": true,
"data": {
"account_id": 11027991,
"signup_fee": ""
}
}| Parameter | Type | Description |
|---|---|---|
| product | string | Select the desired MultiSafepay subscription: Connect 300, Connect 1000 or FastCheckout. |
| company_name | string | Company name of partner. |
| address1 | string | First line of customer’s provided address. |
| address2 | string | Second line of customer’s provided address. |
| zip_code | string | Customer’s provided zip / postal code. |
| city | string | Customer’s provided city. |
| string | Customer’s provided email address. Used to send Second Chance emails and in fraud checks. | |
| country | string | Customer’s provided country code ISO 3166-1 |
| phone | string | Customer’s provided phone number. |
| password | string | Supply a password for creating credentials for partner account. |
| address_apartment | string | |
| software_partner | string | Put on “Anders”. |
| partner | object | |
| api_user | string | User ID of partner account. |
| api_ pass | string | Password for partner account. |
| contact_details | object | |
| title | string | Mr, Mrs or Ms. |
| name | string | Name of partner. |
| bank_details | object | |
| account_number | string | Account number of bank. |
| bank_name | string | Name of bank. |
| country | string | Country of bank ISO 3166-1 |
Create a website profile in MultiSafepay Control
POST - /websites
{
"partner": {
"api_user": "partner-account-user-name",
"api_pass": "partner-account-password",
},
"url": "https://yourpartnerdomain.com",
"return_url": "http://www.example.com/client/notification?type=notification",
"description": "",
"category": "100"
}JSON Response
{
"success": true,
"data": {
"site_id": null,
"secure_code": null,
"api_key": "null
}
}| Parameter | Type | Description |
|---|---|---|
| url | string | Webshop URL. |
| return_url | string | Endpoint where we will send the notifications to. notification_url |
| description | string | The description will be shown on the payment pages and depending on the payment method also shown on the bank or credit statement of your customer. |
| category | string | Select a category related to the webshop. See list below. |
| partner | object | |
| api_user | string | User ID of partner account. |
| api_pass | string | Password for partner account. |
| Code | Type |
|---|---|
| 100 | Gifts and gadgets |
| 101 | Electronics and computers |
| 102 | Games |
| 103 | Health |
| 104 | House and Garden |
| 105 | Office supplies |
| 106 | Kids and toys |
| 107 | Nutrition |
| 108 | Fashion and care |
| 109 | Music, movies and books |
| 110 | Sport, leisure and hobby |
| 111 | Phone and internet |
| 112 | Holiday and travel |
| 113 | Sale and auctions |
| 114 | Other |
| 999 | Adult |
Tools
Server to Server
3D Enabled Request
POST - /orders
{
"type": "direct",
"gateway": "CREDITCARD",
"order_id": "order-1",
"currency": "EUR",
"amount": 1000,
"description": "product description",
"payment_options": {
"notification_url": "http://www.example.com/client/notification?type=notification",
"redirect_url": "http://www.example.com/client/notification?type=redirect",
"cancel_url": "http://www.example.com/client/notification?type=cancel",
"close_window": true
},
"customer": {
"locale": "nl_NL",
"ip_address": "127.0.0.1"
},
"gateway_info": {
"card_number": "4111111111111111",
"card_holder_name": "Holder Name",
"card_expiry_date": "1612",
"cvc": "123"
}
}JSON Response
When 3D secure verification is required, the HTML form will be returned and should be rendered.
"customer_verification": {
"html": "<html>\n<head>\n<title>3D Html form</title>....",
"type": "form"
}| Parameter | Type | Description |
|---|---|---|
| type | string | Specifies the payment flow for the checkout process. Options: direct. |
| gateway | string | The unique gateway id to immediately direct the customer to the payment method. You retrieve these gateways using a gateway request. Option: VISA, MASTERCARD, AMERICAN EXPRESS, MAESTRO and CREDITCARD. |
| order_id | string | The unique identifier from your system for the order. |
| currency | string | The currency ISO-4217 you want the customer to pay with. |
| amount | integer | The amount (in cents) that the customer needs to pay. |
| description | string | A text which will be shown with the order in MultiSafepay Control. If the customer’s bank supports it this will also be shown on the bank statement. Max 200 characters. HTML is no longer supported. Use the ‘items’ or ‘shopping_cart’ objects for this. |
| payment_options | object | |
| notification_url | string | Endpoint where we will send the notifications to. notification_url |
| redirect_url | string | Customer will be redirected to this page after a successful payment. |
| cancel_url | string | Customer will be redirected to this page after a failed payment. |
| customer | object | |
| locale | string | Displays the correct language and payment methods on the Payment page. It also has an influence on sending the set email templates. Use the format ab_CD with ISO 639 language codes and ISO 3166 country codes. Default: en_US. |
| ip_address | string | The IP address of the customer. “Required” with post payment and credit card payment methods. Due to validation of the customer IP address, we need to receive the actual IP address of the end user within the ip_address field. More info |
| gateway_info | object | |
| card_number | string | Full credit card number. |
| card_holder_name | string | Name on the credit card. |
| card_expiry_date | string | Card expire date. |
| card_cvc | string | Card CVC number. This might vary depending of the card type. Some cards like MAESTRO may not be required. |
Please make sure you check out our dedicated documentation on Server to Server.
3D disabled or NON 3D transaction
POST - /orders
{
"type": "direct",
"gateway": "CREDITCARD",
"order_id": "order-1",
"currency": "EUR",
"amount": 1000,
"description": "product description",
"payment_options": {
"notification_url": "http://www.example.com/client/notification?type=notification",
"redirect_url": "http://www.example.com/client/notification?type=redirect",
"cancel_url": "http://www.example.com/client/notification?type=cancel",
"close_window": true
},
"customer": {
"locale": "nl_NL",
"ip_address": "127.0.0.1"
},
"gateway_info": {
"card_number": "4111111111111111",
"card_holder_name": "Holder Name",
"card_expiry_date": "1612",
"cvc": "123"
}
}JSON Response
When no 3D verification is required, the transaction status response will be processed directly and no form will be sent.
{
"success": true,
"data": {
...
}
}| Parameter | Type | Description |
|---|---|---|
| type | string | Specifies the payment flow for the checkout process. Options: direct. |
| gateway | string | The unique gateway id to immediately direct the customer to the payment method. You retrieve these gateways using a gateway request. Option: CREDITCARD. |
| order_id | string | The unique identifier from your system for the order. |
| currency | string | The currency ISO-4217 you want the customer to pay with. |
| amount | integer | The amount (in cents) that the customer needs to pay. |
| description | string | A text which will be shown with the order in MultiSafepay Control. If the customer’s bank supports it this will also be shown on the bank statement. Max 200 characters. HTML is no longer supported. Use the ‘items’ or ‘shopping_cart’ objects for this. |
| payment_options | object | |
| notification_url | string | Endpoint where we will send the notifications to. notification_url |
| redirect_url | string | Customer will be redirected to this page after a successful payment. |
| cancel_url | string | Customer will be redirected to this page after a failed payment. |
| customer | object | |
| locale | string | Displays the correct language and payment methods on the Payment page. It also has an influence on sending the set email templates. Use the format ab_CD with ISO 639 language codes and ISO 3166 country codes. Default: en_US. |
| ip_address | string | The IP address of the customer. “Required” with post payment and credit card payment methods. Due to validation of the customer IP address, we need to receive the actual IP address of the end user within the ip_address field. More info |
| gateway_info | object | |
| card_number | string | Full credit card number. |
| card_holder_name | string | Name on the credit card. |
| card_expiry_date | string | Card expire date. |
| card_cvc | string | Card CVC number. This might vary depending of the card type. Some cards like MAESTRO may not be required. |
Please make sure you check out our dedicated documentation on Server to Server.
Flexible 3D
COMING SOON: Flexible 3D for Server to Server
Direct, Flexible 3D set on false
Flexible 3D is a feature that allows you to enable/disable 3D secure at API level. The Flexible 3D mandates whether or not a transaction should be completed with the 3D secure verification or not.
Credit card transactions which are processed with the 3D Secure protocol require a form of authentication of the customer during the payment process. Setting Flexible 3D to false will disable the verfication process.
Activating Flexible 3D secure will override the rules of the Dynamic 3D settings, meaning that payments will not be enrolled with a 3D authentication.
POST - /orders
{
"type": "direct",
"gateway": "VISA",
"order_id": "my-test-order-01",
"currency": "EUR",
"amount": 100,
"description": "test product description",
"payment_options": {
"notification_url": "http://www.example.com/client/notification?type=notification",
"redirect_url": "http://www.example.com/client/notification?type=redirect",
"cancel_url": "http://www.example.com/client/notification?type=cancel",
"close_window": ""
},
"customer": {
"locale": "nl_NL",
"ip_address": "10.1.5.1",
"first_name": "Testperson-nl",
"last_name": "Approved",
"address1": "Kraanspoor",
"house_number": "39C",
"zip_code": "1033SC",
"city": "Amsterdam",
"country": "NL",
"phone": "0208500500",
"email": "[email protected]",
"referrer": "http://example.com",
"user_agent": "Mozilla/5.0 (Windows NT 6.3; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/38.0.2125.111 Safari/537.36"
},
"gateway_info": {
"flexible_3d": false,
"card_number": "4111111111111111",
"card_holder_name": "MultiSafepay",
"card_expiry_date": "2412",
"term_url": "http://example.com/?type=term&api_key=<api_key>",
"card_cvc": "321"
}
}JSON Response
{
"success": true,
"data": {
"transaction_id": 001,
"order_id": "my-test-order-01",
"created": "2019-05-16T10:51:54",
"currency": "EUR",
"amount": 100,
"description": "test product description",
"var1": null,
"var2": null,
"var3": null,
"items": null,
"amount_refunded": 0,
"status": "completed",
"financial_status": "completed",
"reason": "",
"reason_code": "",
"fastcheckout": "NO",
"modified": "2019-05-16T10:51:54",
"customer": {
"locale": "nl_NL",
"first_name": "Testperson-nl",
"last_name": "Approved",
"address1": "Kraanspoor",
"address2": null,
"house_number": "39C",
"zip_code": "1033SC",
"city": "Amsterdam",
"state": null,
"country": "NL",
"country_name": null,
"phone1": "0208500500",
"phone2": "",
"email": "[email protected]"
},
"custom_info": {
"custom_1": null,
"custom_2": null,
"custom_3": null
},
"payment_details": {
"type": "VISA",
"account_id": null,
"account_holder_name": "MultiSafepay",
"external_transaction_id": 0010,
"last4": 1111,
"card_expiry_date": 2412
},
"costs": [
{
"transaction_id": 001,
"description": "0.0 % For Visa CreditCards Transactions",
"type": "SYSTEM",
"amount": 0.0
}
],
"payment_url": "https://www.example.com/client/notification?type=redirect&transactionid=my-test-order-01",
"cancel_url": "https://www.example.com/client/notification?type=cancel&transactionid=my-test-order-01"
}
}| Parameter | Type | Description |
|---|---|---|
| type | string | Specifies the payment flow for the checkout process. Options: direct. |
| gateway | string | The unique gateway id to immediately direct the customer to the payment method. You retrieve these gateways using a gateway request. Option: VISA and MASTERCARD. |
| order_id | string | The unique identifier from your system for the order. |
| currency | string | The currency ISO-4217 you want the customer to pay with. |
| amount | integer | The amount (in cents) that the customer needs to pay. |
| description | string | A text which will be shown with the order in MultiSafepay Control. If the customer’s bank supports it this will also be shown on the bank statement. Max 200 characters. HTML is no longer supported. Use the ‘items’ or ‘shopping_cart’ objects for this. |
| payment_options | object | Contains the redirect_url, cancel_url and notification_url |
| customer | object | Contains personal information about the customer. |
| gateway_info | object | Defines certain customer data (payment details). |
| flexible_3d | boolean | True, enable the 3D secure authentication. False, disable the 3D secure authentication. |
| term_url | string | URL that is used to instruct the card issuer where to redirect the authorisation query. |
Redirect, Flexible 3D set on false
Flexible 3D is a feature that allows you to enable/disable 3D secure at API level. The Flexible 3D mandates whether or not a transaction should be completed with the 3D secure verification or not.
Credit card transactions which are processed with the 3D Secure protocol require a form of authentication of the customer during the payment process. Setting Flexible 3D to false will disable the verfication process.
Activating Flexible 3D secure will override the rules of the Dynamic 3D settings, meaning that payments will not be enrolled with a 3D authentication.
POST - /orders
{
"type": "redirect",
"gateway": "VISA",
"order_id": "my-order-id-1",
"currency": "EUR",
"amount": 100,
"description": "test product description",
"payment_options": {
"notification_url": "http://www.example.com/client/notification?type=notification",
"redirect_url": "http://www.example.com/client/notification?type=redirect",
"cancel_url": "http://www.example.com/client/notification?type=cancel",
"close_window": ""
},
"customer": {
"locale": "nl_NL",
"ip_address": "10.1.5.1",
"first_name": "Testperson-nl",
"last_name": "Approved",
"address1": "Kraanspoor",
"house_number": "39",
"zip_code": "1033SC",
"city": "Amsterdam",
"country": "NL",
"email": "[email protected]",
"referrer": "http://example.com",
"user_agent": "Mozilla/5.0 (Windows NT 6.3; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/38.0.2125.111 Safari/537.36"
},
"gateway_info": {
"flexible_3d": false,
"term_url": "http://example.com/?type=term&api_key=<api_key>"
}
}JSON Response
{
"success": true,
"data": {
"order_id": "my-order-id-1",
"payment_url": "https://payv2.multisafepay.com/connect/13oElUaESR7YS2b4gUJV9oI4tUXeb1mj1D8/?lang=nl_NL"
}
}| Parameter | Type | Description |
|---|---|---|
| type | string | Specifies the payment flow for the checkout process. Options: redirect. |
| gateway | string | The unique gateway id to immediately direct the customer to the payment method. You retrieve these gateways using a gateway request. Option: VISA and MASTERCARD. |
| order_id | string | The unique identifier from your system for the order. |
| currency | string | The currency ISO-4217 you want the customer to pay with. |
| amount | integer | The amount (in cents) that the customer needs to pay. |
| description | string | A text which will be shown with the order in MultiSafepay Control. If the customer’s bank supports it this will also be shown on the bank statement. Max 200 characters. HTML is no longer supported. Use the ‘items’ or ‘shopping_cart’ objects for this. |
| payment_options | object | Contains the redirect_url, cancel_url and notification_url |
| customer | object | |
| locale | string | Displays the correct language and payment methods on the Payment page. It also has an influence on sending the set email templates. Use the format ab_CD with ISO 639 language codes and ISO 3166 country codes. Default: en_US. |
| ip_address | string | The IP address of the customer. “Required” with post payment and credit card payment methods. Due to validation of the customer IP address, we need to receive the actual IP address of the end user within the ip_address field. More info |
| first_name | string | The customer’s first name. |
| last_name | string | The customer’s last name. |
| address1 | string | First line of customer’s provided address. |
| house_number | string | Customer’s provided house number. |
| zip_code | string | Customer’s provided zip / postal code. |
| city | string | Customer’s provided city. |
| country | string | Customer’s provided country code ISO 3166-1 |
| phone | string | Customer’s provided phone number. |
| string | Customer’s provided email address. Used to send Second Chance emails and in fraud checks. | |
| gateway_info | object | |
| flexible_3d | boolean | True, enable the 3D secure authentication. False, disable the 3D secure authentication. |
| term_url | string | URL that is used to instruct the card issuer where to redirect the authorisation query. |
Redirect, Flexible 3D set on true
It is mandatory to enable Flexible 3D secure processing in this call, even when Dynamic 3D rules could set the settings to disable it.
Flexible 3D is a feature that allows you to enable/disable 3D secure at API level. The Flexible 3D mandates whether or not a transaction should be completed with the 3D secure verification or not.
When Flexible 3D is set on true, the authentication verification is mandatory to finalize and release a successful payment. Credit card transactions which are processed without the 3D Secure protocol, are now required to complete the 3D secure verification. Activating Flexible 3D secure will override the rules of the Dynamic 3D settings, meaning that the payment will be enrolled with a 3D Secure authentication.
POST - /orders
{
"type": "redirect",
"gateway": "MASTERCARD",
"order_id": "my-order-id-01",
"currency": "EUR",
"amount": 100,
"description": "test product description",
"payment_options": {
"notification_url": "http://www.example.com/client/notification?type=notification",
"redirect_url": "http://www.example.com/client/notification?type=redirect",
"cancel_url": "http://www.example.com/client/notification?type=cancel",
"close_window": true
},
"customer": {
"locale": "nl_NL",
"ip_address": "10.1.5.1",
"first_name": "Testperson-nl",
"last_name": "Approved",
"address1": "Kraanspoor",
"house_number": "39",
"zip_code": "1033SC",
"city": "Amsterdam",
"country": "NL",
"email": "[email protected]",
"referrer": "http://example.com",
"user_agent": "Mozilla/5.0 (Windows NT 6.3; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/38.0.2125.111 Safari/537.36"
},
"gateway_info": {
"flexible_3d": true,
"term_url": "http://example.com/?type=term&api_key=<api_key>"
}
}JSON Response
{
"success": true,
"data": {
"order_id": "my-order-id-01",
"payment_url": "https://payv2.multisafepay.com/connect/13oElUaESR7YS2b4gUJV9oI4tUXeb1mj1D8/?lang=nl_NL"
}
}| Parameter | Type | Description |
|---|---|---|
| type | string | Specifies the payment flow for the checkout process. Options: redirect. |
| gateway | string | The unique gateway id to immediately direct the customer to the payment method. You retrieve these gateways using a gateway request. Option: VISA and MASTERCARD. |
| order_id | string | The unique identifier from your system for the order. |
| currency | string | The currency ISO-4217 you want the customer to pay with. |
| amount | integer | The amount (in cents) that the customer needs to pay. |
| description | string | A text which will be shown with the order in MultiSafepay Control. If the customer’s bank supports it this will also be shown on the bank statement. Max 200 characters. HTML is no longer supported. Use the ‘items’ or ‘shopping_cart’ objects for this. |
| payment_options | object | |
| notification_url | string | Endpoint where we will send the notifications to. notification_url |
| notification_method | string | Sends push notification (POST,GET) default: GET. |
| redirect_url | string | Customer will be redirected to this page after a successful payment. |
| cancel_url | string | Customer will be redirected to this page after a failed payment. |
| customer | object | |
| locale | string | Displays the correct language and payment methods on the Payment page. It also has an influence on sending the set email templates. Use the format ab_CD with ISO 639 language codes and ISO 3166 country codes. Default: en_US. |
| ip_address | string | The IP address of the customer. “Required” with post payment and credit card payment methods. Due to validation of the customer IP address, we need to receive the actual IP address of the end user within the ip_address field. More info |
| first_name | string | The customer’s first name. |
| last_name | string | The customer’s last name. |
| address1 | string | First line of customer’s provided address. |
| house_number | string | Customer’s provided house number. |
| zip_code | string | Customer’s provided zip / postal code. |
| city | string | Customer’s provided city. |
| country | string | Customer’s provided country code ISO 3166-1 |
| phone | string | Customer’s provided phone number. |
| string | Customer’s provided email address. Used to send Second Chance emails and in fraud checks. | |
| gateway_info | object | |
| flexible_3d | boolean | True, enable the 3D secure authentication. False, disable the 3D secure authentication. |
| term_url | string | URL that is used to instruct the card issuer where to redirect the authorisation query. |
Generating a payment link
For several scenarios, it can be useful for our merchants to generate a payment link. The payment link allows MultiSafepay Control to create a unique transaction that the payment can be matched with.
POST - /orders
{
"type": "paymentlink",
"order_id": "test-123",
"gateway": "",
"currency": "EUR",
"amount": "1000",
"description": "Test Order Description",
"payment_options": {
"notification_url": "http://www.example.com/client/notification?type=notification",
"redirect_url": "http://www.example.com/client/notification?type=redirect",
"cancel_url": "http://www.example.com/client/notification?type=cancel",
"close_window": ""
},
"customer": {
"locale": "en_US"
}
}JSON Response
{
"success": true,
"data": {
"order_id": "test-123",
"payment_url": "https://devpayv2.multisafepay.com/connect/89QENbhQYcJoP2CO0kx6pSRrw8v2JFnTynr/?lang=nl_NL"
}
}| Parameter | Type | Description |
|---|---|---|
| type | string | Specifies the payment flow for the checkout process. Fill in ‘paymentlink’. |
| order_id | string | The unique identifier from your system for the order. Required. Max 50 char. |
| currency | string | The currency ISO-4217 you want the customer to pay with. |
| amount | integer | The amount (in cents) that the customer needs to pay. |
| description | string | A text which will be shown with the order in MultiSafepay Control. If the customer’s bank supports it this will also be shown on the bank statement. Max 200 characters. HTML is no longer supported. Use the ‘items’ or ‘shopping_cart’ objects for this. |
| gateway (optional) | string | The unique gateway id to immediately direct the customer to the payment method. You retrieve these gateways using a gateway request. |
The rest of the fields are optional.