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.

TEST API

https://testapi.multisafepay.com/v1/json

LIVE API

https://api.multisafepay.com/v1/json

Environments

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.

TEST Merchant Panel

LIVE Merchant Panel

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

Open a TEST Account

GET - /gateways?locale=es

Localization

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.

Discount

If you, as an online store, want to apply a discount before a payment request is made, it is recommended to take into account how you process the discount with postpaid payment methods.

Because MultiSafepay validates the shopping cart of postpaid payment method orders, it is advised to submit the discount in the unit price. In spite of the fact that the discount added as an order rule will be accepted, it is advisable to indicate the discount as unit price. The reason why adding the discount in the unit price is recommened is because of a partial refund. Adding a discount as a seperate discount rule creates an issue with partial refunding because the negative amount cannot be undone.

Add the discount as unit price when you process postpaid payment methods

Discount added as order rule (which is non-refundable)

Adding a discount as order rule is a common way to add a discount before submitting a transaction request at MultiSafepay. However, adding a discount as order rule may result in a conflict when partial refunding a postpaid payment method transaction. This is most common when the discount is a percentage. Adding a discount as seperate discount rule, will conflict with parcially refunding a postpaid payment method transaction as the negative amount cannot be undone. It is not possible to partially refund a negative amount that is added as a discount rule.

Example with discount in separate order rule:

{
	"type": "redirect",
	"gateway": "PAYAFTER",
	"order_id": "apitool_7670065",
	"currency": "EUR",
	"amount": 20800,
	"description": "Test Order Description",
	"var1": "",
	"var2": "",
	"var3": "",
	"items": "",
	"manual": "false",
	"gateway_info": {
		"birthday": "1980-01-30",
		"bank_account": "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": ""
	},
	"plugin": {
		"shop": "ApiTestTool",
		"plugin_version": "1.0.0",
		"shop_version": "1",
		"partner": "parner",
		"shop_root_url": "http://multisafepay.com"
	},
	"customer": {
		"locale": "us",
		"ip_address": "80.123.456.789",
		"first_name": "Testperson-nl",
		"last_name": "Approved",
		"address1": "Kraanspoor",
		"address2": "",
		"house_number": "39c",
		"zip_code": "1033 SC",
		"city": "AMSTERDAM",
		"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": "Kraanspoor",
		"address2": "",
		"house_number": "39c",
		"zip_code": "1033 SC",
		"city": "AMSTERDAM",
		"state": "",
		"country": "NL",
		"phone": "",
		"email": ""
	},
	"shopping_cart": {
		"items": [{
				"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": 2,
				"merchant_item_id": "333333",
				"tax_table_selector": "none",
				"weight": {
					"unit": "KG",
					"value": 20
				}
			},
			{
				"name": "Flat Rate - Fixed",
				"description": "Shipping",
				"unit_price": 10,
				"quantity": 1,
				"merchant_item_id": "msp-shipping",
				"tax_table_selector": "none",
				"weight": {
					"unit": "KG",
					"value": 0
				}
			}, {
				"name": "20% discount on all items",
				"description": "Discount",
				"unit_price": -52,
				"quantity": 1,
				"merchant_item_id": "discount",
				"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"
						}
					]
				}
			]
		}
	}
}

Discount added as unit price

A discount added as seperate discount rule may conflict in refunding with postpaid payment methods. Therefore, it is advised to add the discount as unit price. As a result, no negative order rule is created, which means that refunding from a postpaid payment method will not cause a conflict.

Example with 20% discount calculated in all unit prices:

{
    "type": "redirect",
    "gateway": "PAYAFTER",
    "order_id": "apitool_5313092",
    "currency": "EUR",
    "amount": 20800,
    "description": "Test Order Description",
    "var1": "",
    "var2": "",
    "var3": "",
    "items": "",
    "manual": false,
    "gateway_info": {
        "birthday": "1980-01-30",
        "bank_account": "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": ""
    },
    "plugin": {
        "shop": "ApiTestTool",
        "plugin_version": "1.0.0",
        "shop_version": "1",
        "partner": "parner",
        "shop_root_url": "https://multisafepay.com"
    },
    "customer": {
        "locale": "us",
        "ip_address": "80.123.456.789",
        "forwarded_ip": "",
        "first_name": "Testperson-nl",
        "last_name": "Approved",
        "address1": "Kraanspoor",
        "address2": "",
        "house_number": "39c",
        "zip_code": "1033 SC",
        "city": "AMSTERDAM",
        "state": "",
        "country": "NL",
        "email": "[email protected]"
    },
    "delivery": {
        "first_name": "Testperson-nl",
        "last_name": "Approved",
        "address1": "Kraanspoor",
        "address2": "",
        "house_number": "39c",
        "zip_code": "1033 SC",
        "city": "AMSTERDAM",
        "state": "",
        "country": "NL",
        "phone": "",
        "email": ""
    },
    "shopping_cart": {
        "items": [
            {
                "name": "Geometric Candle Holders",
                "description": "",
                "unit_price": 72,
                "quantity": 2,
                "merchant_item_id": "111111",
                "tax_table_selector": "none",
                "weight": {
                    "unit": "KG",
                    "value": 12
                }
            },
            {
                "name": "Nice apple",
                "description": "",
                "unit_price": 28,
                "quantity": 2,
                "merchant_item_id": "333333",
                "tax_table_selector": "none",
                "weight": {
                    "unit": "KG",
                    "value": 20
                }
            },
            {
                "name": "Flat Rate - Fixed",
                "description": "Shipping",
                "unit_price": 8,
                "quantity": 1,
                "merchant_item_id": "msp-shipping",
                "tax_table_selector": "none",
                "weight": {
                    "unit": "KG",
                    "value": 0
                }
            },
            {
                "name": "20% discount on all items",
                "description": "Discount",
                "unit_price": 0,
                "quantity": 1,
                "merchant_item_id": "discount",
                "tax_table_selector": "none"
            }
        ]
    },
    "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"
                        }
                    ]
                }
            ]
        }
    }
}

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.

GET - /gateways

JSON Response

{
  "success": true,
  "data": [
    {
      "id": "MASTERCARD",
      "description": "Mastercard"
    },
    {
      "id": "VISA",
      "description": "Visa"
    },
    {
      "id": "AMEX",
      "description": "AMEX",
    }, 
  ]
}

GET - /gateways/{id} JSON Response

{
  "success": true,
  "data": {
    "id": "{id}",
    "description": "{description of payment method}"
  }
}

Retrieve a gateway

Parameter	Type	Description
id	string	The unique identifier of the gateway to be returned.

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"
        }
    ]
}

Retrieve gateways - Multiple available giftcards

Parameter	Type	Description
include=coupons	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.

If the parameter ìnclude=coupons is not added in the retrieve gateway request, only one coupon will be displayed in the response.

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"
    }
  ]
}

Gateway Issuers

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.

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": "80.123.456.789",
        "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"
  }
}

Create a Redirect order

A Redirect order is the default type.

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	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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. Read more about Google Analytics on the 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. In the event that the transaction is marked with the status uncleared, the customer will also be redirected to the thank-you page of the webshop. The uncleared status will not be passed on to the customer who will experience the payment as successful at all times.
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.
email	string	Customer’s provided email address. Used to send Second Chance emails and in fraud checks.

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"
  }
}

Create 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	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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. In the event that the transaction is marked with the status uncleared, the customer will also be redirected to this page of the webshop. The uncleared status will not be passed on to the customer who will experience the payment as successful at all times.
cancel_url	string	Customer will be redirected to this page after a failed 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 Payment

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 please visit our documentation page to read more about recurring payments

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	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
recurring_id	integer	The unique recurring id used for recurring payments.
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. In the event that the transaction is marked with the status uncleared, the customer will also be redirected to this page of the webshop. The uncleared status will not be passed on to the customer who will experience the payment as successful at all times.
cancel_url	string	Customer will be redirected to this page after a failed payment.

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"
  }
}

Split Payments

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.

Read more about split payments on our documentation 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	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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. In the event that the transaction is marked with the status uncleared, the customer will also be redirected to this page of the webshop. The uncleared status will not be passed on to the customer who will experience the payment as successful at all times.
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.

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 an order

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

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": "Kraanspoor",
      "address2": null,
      "house_number": "39",
      "zip_code": "1033 SC",
      "city": "Amsterdam",
      "state": null,
      "country": "NL",
      "country_name": null,
      "phone1": "020 8500 500",
      "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"
      }
    ]
  }
}

Retrieve an order

Get order status & information. Depending on the order type or method, the structure may be different.

Parameter	Type	Description
order_id	integer / string	The unique identifier of the order to be returned. If the values are only numbers the type will be integer, otherwise it will be string.

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"
  }
}

Dynamic Template

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	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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. In the event that the transaction is marked with the status uncleared, the customer will also be redirected to this page of the webshop. The uncleared status will not be passed on to the customer who will experience the payment as successful at all times.
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)

POST - /orders

{
    "type": "direct",
    "gateway": "AFTERPAY",
    "order_id": "my-order-id-1",
    "currency": "EUR",
    "amount": "37380",
    "description": "Test Order Description",
    "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": "Kraanspoor",
        "house_number": "39",
        "zip_code": "1033 SC",
        "city": "Amsterdam",
        "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": "Kraanspoor",
        "house_number": "39",
        "zip_code": "1033 SC",
        "city": "Amsterdam",
        "country": "NL",
        "phone": "0208500500",
        "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": "NL"
                        },
                        {
                            "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",
        "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": "Kraanspoor",
            "house_number": "39C",
            "zip_code": "1033 SC",
            "city": "Amsterdam",
            "country": "NL",
            "country_name": null,
            "phone1": "020 8500 500",
            "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": "NL"
                        },
                        {
                            "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"
    }
}

POST - /orders

{
    "type": "redirect",
    "gateway": "AFTERPAY",
    "order_id": "my-order-id-1",
    "currency": "EUR",
    "amount": 37485,
    "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", 
        "close_window": ""
    },
    "customer": {
        "locale": "nl_NL",
        "first_name": "Testperson-nl",
        "last_name": "Approved",
        "address1": "Kraanspoor",
        "house_number": "39",
        "zip_code": "1033 SC",
        "city": "Amsterdam",
        "country": "NL",
        "email": "[email protected]"
    },
    "delivery": {
        "first_name": "Testperson-nl",
        "last_name": "Approved",
        "address1": "Kraanspoor",
        "house_number": "39",
        "zip_code": "1033 SC",
        "city": "Amsterdam",
        "country": "NL",
        "phone": "0208500500",
        "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": "BTW9",
                "weight": {
                    "unit": "KG",
                    "value": "20"
                }
            },
            {
                "name": "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": "BTW9",
                    "standalone": true,
                    "rules": [
                        {
                            "rate": 0.09
                        }
                    ]
                },
                {
                    "name": "BTW6",
                    "standalone": true,
                    "rules": [
                        {
                            "rate": 0.06
                        }
                    ]
                },
                {
                    "name": "BTW0",
                    "standalone": true,
                    "rules": [
                        {
                            "rate": 0
                        }
                    ]
                },
                {
                    "name": "none",
                    "standalone": false,
                    "rules": [
                        {
                            "rate": 0
                        }
                    ]
                },
                {
                    "name": "FEE",
                    "standalone": false,
                    "rules": [
                        {
                            "rate": 0
                        }
                    ]
                }
            ]
        }
    }
}

JSON Response

{
    "success": true,
    "data": {
        "order_id": "my-order-id-1",
        "payment_url": "https://payv2.multisafepay.com/connect/137LMJCe0GP8238bseHBnf97COSGr7mKGku/?lang=nl_NL"
    }
}

AfterPay

Direct - AfterPay

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	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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.
email	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.
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).

Read more about AfterPay on our documentation page.

Redirect - AfterPay

Creates an AfterPay order to be paid after delivery.

Redirect 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	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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.
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

Read more about AfterPay on our documentation page.

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": "cn_CN"
    }
}

JSON Response

{
    "success": true,
    "data": {
        "order_id": "my-order-id-1",
        "payment_url": "https://payv2.multisafepay.com/connect/13oElUaESR7YS2b4gUJV9oI4tUXeb1mj1D8/?lang=nl_NL"
    }
}

POST - /orders

{
    "type": "direct",
    "order_id": "my-order-id-1",
    "gateway": "ALIPAY",
    "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",
        "close_window": ""
    },
    "customer": {
        "locale": "cn_CN",
        "ip_address": "89.20.162.110",
        "forwarded_ip": "",
        "first_name": "Testperson-nl",
        "last_name": "Approved",
        "address1": "Kraanspoor",
        "address2": "",
        "house_number": "39C",
        "zip_code": "1033 SC",
        "city": "Amsterdam",
        "country": "NL",
        "phone": "020 8500 500",
        "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"
    }
}

JSON Response

{
    "success": true,
    "data": {
        "transaction_id": 2379429850,
        "order_id": "my-order-id-1",
        "created": "2020-01-08T10:51:04",
        "currency": "EUR",
        "amount": 1000,
        "description": "Test Order Description",
        "items": null,
        "amount_refunded": 0,
        "status": "initialized",
        "financial_status": "initialized",
        "reason": "",
        "reason_code": "",
        "fastcheckout": "NO",
        "modified": "2020-01-08T10:51:04",
        "customer": {
            "first_name": "Testperson-nl",
            "last_name": "",
            "address1": "Kraanspoor",
            "address2": null,
            "house_number": 39C,
            "city": "Amsterdam",
            "country": "NL",
            "country_name": null,
            "zip_code": "1033 SC"
            "email": "[email protected]",
            "locale": "cn_CN",
            "phone1": "020 8500 500",
        },
        "payment_details": {
            "type": "ALIPAY"
           	 "account_holder_name": null,
            "account_id": "",
            "external_transaction_id": null,
            "recurring_id": null,
            "recurring_model": null,
        },
        "costs": [
            {
                "amount": ,
                "description": "",
                "type": "SYSTEM"
            },
            "payment_methods": [
                {
                    "account_id": "",
                    "amount": 1000,
                    "currency": "EUR",
                    "description": "Test Order Description",
                    "payment_description": "ALIPAY",
                    "status": "initialized",
                    "type": "ALIPAY"
                }
            ],
            "payment_url": "https://excashier.alipay.com/standard/auth.htm?auth_order_id=exc_5fc2c0045b9b455f87fedd6d7f41f021"
        }
    }

Alipay

Redirect

All parameters shown are required field(s) for an Alipay redirect transaction.

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	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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

Read more about Alipay on our documentation page.

Direct

All parameters shown are required field(s) for an Alipay direct transaction.

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	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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

Read more about Alipay on our documentation page.

POST - /orders

{
    "type": "redirect",
    "order_id": "my-order-id-1",
    "gateway": "AMEX",
    "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": "nl_NL",
    "ip_address": "127.0.0.1"
}

JSON Response

{
  "success": true,
  "data": {
    "order_id": "my-order-id-1",
    "payment_url": "https://payv2.multisafepay.com/connect/13oElUaESR7YS2b4gUJV9oI4tUXeb1mj1D8/?lang=nl_NL"
  }
}

American Express

The customer will be redirected to a payment page of MultiSafepay for this credit card. The customer will be requested to fill in his credit card credentials.

All parameters shown are required.

Parameter	Type	Description
type	string	Specifies the payment flow for the checkout process. Options: redirect.
gateway	string	Fixed value: AMEX
order_id	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
currency	string	The currency ISO-4217 you want the customer to pay with.
amount	integer	The amount (in cents) that the customer has 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. In the event that the transaction is marked with the status uncleared, the customer will also be redirected to the thank-you page of the webshop. The uncleared status will not be passed on to the customer who will experience the payment as successful at all times.
cancel_url	string	Customer will be redirected to this page after a failed payment.

Read more about American Express on our documentation page.

POST - /orders

{
    "type": "redirect",
    "order_id": "my-order-id-1",
    "gateway": "",
    "currency": "EUR",
    "amount": "9743",
    "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",
        "close_window": ""
    },

JSON Response

{
  "success": true,
  "data": {
    "order_id": "my-order-id-1",
    "payment_url": "https://payv2.multisafepay.com/connect/13ztRF4ic5Kz23n2Lf5F3UzcVqMRxwjlfQw/?lang=nl_NL"
  }
}

POST - /orders

{
    "type": "redirect",
    "order_id": "my-order-id-1",
    "gateway": "APPLEPAY",
    "currency": "EUR",
    "amount": "9743",
    "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",
        "close_window": ""
    },

JSON Response

{
  "success": true,
  "data": {
    "order_id": "my-order-id-1",
    "payment_url": "https://payv2.multisafepay.com/connect/13ztRF4ic5Kz23n2Lf5F3UzcVqMRxwjlfQw/?lang=nl_NL"
  }
}

Apple Pay

All parameters shown are required field(s) for a Apple Pay Redirect transaction.

How to detect Apple Pay on a device

try {
    if (window.ApplePaySession && ApplePaySession.canMakePayments()) {
    console.log('ApplePay available');
    }
    } catch (error) {
    console.debug('An error occurred while verifying if Apple Pay is available:', error);
    }

If this code is not implemented in your back-end platform, consumers choosing Apple Pay on the payment page will be displayed an error if their device does not support Apple Pay, thus we highly reccomend using the abovementioned code to avoid any issues.

Parameter	Type	Description
type	string	Specifies the payment flow for the checkout process. Options: Redirect.
gateway	string	The payment gateway does not need to be specified.
order_id	string\|integer	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
currency	string	The currency ISO-4217 you want the customer to pay with.
amount	integer	The amount (in cents) that the customer has 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. In the event that the transaction is marked with the status uncleared, the customer will also be redirected to the thank-you page of the webshop. The uncleared status will not be passed on to the customer who will experience the payment as successful at all times.
cancel_url	string	Customer will be redirected to this page after a failed payment.

Apple Pay Direct

All parameters shown are required field(s) for a Apple Pay Direct transaction. Please note this is a simply a Redirect call with ‘APPLEPAY’ pre-selected.

It must be noted that the ‘gateway’ parameter for the Apple Pay direct transaction must be set to ‘APPLEPAY’ in order for Apple Pay to be preselected on the payment page. The payment page will detect whether the device being used supports Apple Pay or not.

If the device supports Apple Pay, the user will be directed to the Apple Pay interface where a payment can be completed. If the device does not support Apple Pay, an error will be displayed. The following code will allow the detection of Apple Pay. This can be implemented to your platform:

How to detect Apple Pay on a device

try {
    if (window.ApplePaySession && ApplePaySession.canMakePayments()) {
    console.log('ApplePay available');
    }
    } catch (error) {
    console.debug('An error occurred while verifying if Apple Pay is available:', error);
    }

Parameter	Type	Description
type	string	Specifies the payment flow for the checkout process. Options: Redirect.
gateway	string	Fixed value: APPLEPAY
order_id	string\|integer	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
currency	string	The currency ISO-4217 you want the customer to pay with.
amount	integer	The amount (in cents) that the customer has 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. In the event that the transaction is marked with the status uncleared, the customer will also be redirected to the thank-you page of the webshop. The uncleared status will not be passed on to the customer who will experience the payment as successful at all times.
cancel_url	string	Customer will be redirected to this page after a failed payment.

Read more about Apple Pay on our documentation page.

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"
    }
}

Bancontact

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

Read more about Bancontact on our documentation page.

POST - /orders

{
    "type": "redirect",
    "order_id": "my-order-id-1",
    "gateway": "MISTERCASH",
    "currency": "EUR",
    "amount": "1009",
    "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_enabled": 1
    },
    "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",
        "qr_url": "https://payv2.multisafepay.com/simulator/qr?mtp_method=mistercash&token=xxxx"
    }
}

Bancontact QR

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	integer / string	The unique identifier from your system for the order.
currency	string	Has to be EUR.
amount	integer	The amount (in cents) that the customer has 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
gateway_info	object	The qr_enabled = 1 invokes the qr_url. This parameter contains a deeplink to Bancontact/MisterCash which can be encoded into a QR image at any later point. This QR image generation can be done at a bpost systems or within the postman application at bpost (if possible).
customer	object

Read more about Bancontact on our documentation page.

POST - /orders

{
    "type": "redirect",
    "order_id": "my-order-id-1",
    "currency": "EUR",
    "amount": 1000,
    "gateway": "BANKTRANS",
    "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": true
    },
    "customer": {
        "locale": "nl_NL",
        "ip_address": "89.20.162.110"
        "email": "[email protected]"
    }
}

JSON Response

{
    "success": true,
    "data": {
        "order_id": "my-order-id-1",
        "payment_url": "https://payv2.multisafepay.com/connect/13UeQHxVIs83238WIJdlSYsB4owgNSqZudS/?lang=nl_NL"
    }
}

POST - /orders

{
    "type": "direct",
    "order_id": "my-order-id-1",
    "currency": "EUR",
    "amount": 1000,
    "gateway": "BANKTRANS",
    "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": true
    },
    "customer": {
        "locale": "nl_NL",
        "ip_address": "89.20.162.110",
    }
}

JSON Response

{
    "success": true,
    "data": {
        "transaction_id": 343755759,
        "order_id": "my-order-id-1",
        "created": "2019-03-01T16:12:47",
        "currency": "EUR",
        "amount": 1000,
        "description": "Test Order Description",
        "var1": null,
        "var2": null,
        "var3": null,
        "items": null,
        "amount_refunded": 0,
        "status": "initialized",
        "financial_status": "initialized",
        "reason": "",
        "reason_code": "",
        "fastcheckout": "NO",
        "modified": "2020-01-06T10:47:18",
        "customer": {
            "address1": null,
            "address2": null,
            "city": null,
            "country": "NL",
            "country_name": null,
            "email": "[email protected]",
            "first_name": null,
            "house_number": null,
            "last_name": null,
            "locale": "nl_NL",
            "phone1": null,
            "phone2": "",
            "state": null,
            "zip_code": null
        },
        "payment_details": {
            "type": "BANKTRANS"
            "account_holder_name": "",
            "account_id": null,
            "external_transaction_id": "9201727123406700",
            "issuer_id": "vib",
            "recurring_id": null,
            "recurring_model": null,
        },
        "costs": [
            {
                "transaction_id": 343755759,
                "amount": 0,
                "description": "",
                "type": "SYSTEM"
            },
        "payment_methods": {
                "account_holder_name": " ",
                "amount": 1000,
                "currency": "EUR",
                "description": "Test Order Description",
                "external_transaction_id": "234374824",
                "payment_description": "Bank Transfer",
                "status": "initialized",
                "type": "BANKTRANS"
            }
        }
        "gateway_info": {
            "NL07DEUT7351106754": "NL07DEUT7351106754",
            "reference": "234374824",
            "issuer_name": "DB",
            "destination_holder_name": "MultiSafepay",
            "destination_holder_city": "Amsterdam",
            "destination_holder_country": "NL",
            "destination_holder_iban": "NL07DEUT7351106754",
            "destination_holder_swift": "DEUTNL2NXXX",
            "account_holder_country": "NL"
        },
        "payment_url": "http://www.example.com/client/notification?type=redirect&transactionid=apitool_13890779",
        "cancel_url": "http://www.example.com/client/notification?type=cancel&transactionid=apitool_13890779"
    }
}

Please note: The parameter ‘email’ must be present, otherwise MultiSafepay will be unable to send the payment details to the customer.

Bank transfer

Redirect - Bank transfer

The bank transfer payment method can either be a direct or redirect order. In this case, the API calls for a redirect order are illustrated; therefore the customer will be redirected to the MultiSafepay payment page. Read more about creating a redirect order

Parameter	Type	Description
type	string	Specifies the payment flow for the checkout process. Options: direct, redirect, checkout, paymentlink.
order_id	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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. Options: BANKTRANS.
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
email	string	The email address where the system can send payment instructions to the customer.

Read more about bank transfers on our documentation page.

Direct - Bank transfer

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	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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.

In the JSON response for a direct transaction, it is important to send payment 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.

{
    "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": "be_BE"
    }
}

JSON Response

{
    "success": true,
    "data": {
        "order_id": "my-order-id-1",
        "payment_url": "https://payv2.multisafepay.com/connect/13oElUaESR7YS2b4gUJV9oI4tUXeb1mj1D8/?lang=nl_NL"
    }
}

POST - /orders

{
    "type": "direct",
    "order_id": "my-order-id-1",
    "currency": "EUR",
    "amount": 1000,
    "gateway": "BELFIUS",
    "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"
    }
}

JSON Response

{
    "success": true,
    "data": {
        "transaction_id": "279354751",
        "order_id": "my-order-id-1",
        "created": "2019-03-07T13:41:15",
        "currency": "EUR",
        "amount": 1000,
        "description": "Test Order Description",
        "items": null,
        "amount_refunded":"0",
        "status": "initialized",
        "financial_status": "initialized",
        "reason": "",
        "reason_code": "",
        "fastcheckout": "NO",
        "modified": "2020-01-07T13:41:15",
        "customer": {
            "locale": "be_BE",
            "first_name": "Testperson-nl",
            "address1": "Kraanspoor",
            "address2": null,
            "house_number": "39",
            "zip_code": "1033 SC"
            "city": "Amsterdam",
            "country": "NL";,
            "country_name": "Netherlands",
            "phone1": "020 8500 500",
            "email": "",
},
        "payment_details": {
            "recurring_id": null,
            "type": "BELFIUS"
"account_id": "https://testpayv2.multisafepay.com/simulator/belfius?transactionid=4014723&return_url=https%3A%2F%2Ftestpay.multisafepay.com%2Fdirect%2Fcomplete%2F&cancel_url=https%3A%2F%2Ftestpay.multisafepay.com%2Fdirect%2Fcomplete%2F&AMOUNT=1000&CURRRENCY=EUR&mspid=4014723",
            "account_holder_name": null,
            "external_transaction_id": "279354751",
},
        "costs": [
{
        "transaction_id": "279354751",
        "description": "Test Order Description",
        "type": "BELFIUS"
        "amount": "1000",
},
        "payment_methods": [
                "account_id": "https://testpayv2.multisafepay.com/simulator/belfius?transactionid=4014723&return_url=https%3A%2F%2Ftestpay.multisafepay.com%2Fdirect%2Fcomplete%2F&cancel_url=https%3A%2F%2Ftestpay.multisafepay.com%2Fdirect%2Fcomplete%2F&AMOUNT=1000&CURRRENCY=EUR&mspid=4014723",
                "currency": "EUR",
                "external_transaction_id": "279354751",
                "payment_description": "",
                "status": "initialized",
}
],
  "payment_url": "https://testpayv2.multisafepay.com/simulator/belfius?transactionid=4014723&return_url=https%3A%2F%2Ftestpay.multisafepay.com%2Fdirect%2Fcomplete%2F&cancel_url=https%3A%2F%2Ftestpay.multisafepay.com%2Fdirect%2Fcomplete%2F&AMOUNT=1000&CURRRENCY=EUR&mspid=4014723"
    }
}

Belfius

Redirect

All parameters shown are required field(s) for a Belfius Redirect transaction.

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	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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

Direct

All parameters shown are required field(s) for a Belfius Direct transaction.

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	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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
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.

Read more about Belfius on our documentation page.

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"
  }
}

Co-branded credit card

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	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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. In the event that the transaction is marked with the status uncleared, the customer will also be redirected to this page of the webshop. The uncleared status will not be passed on to the customer who will experience the payment as successful at all times.
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 Co-branded credit card will only be shown if the locale is correctly supplied in a transaction request.

Please make sure to read more about CartaSi, Cartes Bancaires, Dankort and Postepay on our documentation page.

POST - /orders

{
    "type": "redirect",
    "order_id": "my-order-id-1",
    "gateway": "CREDITCARD",
    "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": "nl_NL",
    "ip_address": "127.0.0.1"
}

JSON Response

{
  "success": true,
  "data": {
    "order_id": "my-order-id-1",
    "payment_url": "https://payv2.multisafepay.com/connect/13oElUaESR7YS2b4gUJV9oI4tUXeb1mj1D8/?lang=nl_NL"
  }
}

Credit Cards

In this payment method the customer will be redirected to a credit card payment page of MultiSafepay. The customer will be requested to fill in their credit card credentials. MultiSafepay will automatically detect which credit card is being used based on the first couple of digits.

All parameters shown are required.

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. Options: CREDITCARD
order_id	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
currency	string	The currency ISO-4217 you want the customer to pay with.
amount	integer	The amount (in cents) that the customer has 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. In the event that the transaction is marked with the status uncleared, the customer will also be redirected to the thank-you page of the webshop. The uncleared status will not be passed on to the customer who will experience the payment as successful at all times.
cancel_url	string	Customer will be redirected to this page after a failed payment.

Read more about credit cards on our documentation page.

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"
    }
}

Dotpay

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	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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

Read more about Dotpay on our documentation page.

POST - /orders

{
    "type": "direct",
    "gateway": "EINVOICE",
    "order_id": "my-order-id-1",
    "currency": "EUR",
    "amount": "26000",
    "description": "Test Order Description",
    "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": "nl_NL",
        "ip_address": "31.148.195.10",
        "forwarded_ip": "",
        "first_name": "Testperson-nl",
        "last_name": "Approved",
        "address1": "Kraanspoor",
        "house_number": "39C",
        "zip_code": "1033 SC",
        "city": "Amsterdam",
        "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": "Kraanspoor",
        "house_number": "39C",
        "zip_code": "1033 SC",
        "city": "Amsterdam",
        "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": "NL"
                        },
                        {
                            "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",
        "items": "",
        "amount_refunded": 0,
        "status": "completed",
        "financial_status": "initialized",
        "reason": "",
        "reason_code": "",
        "fastcheckout": "NO",
        "modified": "2017-09-29T16:13:10",
        "customer": {
            "locale": "nl_NL",
            "first_name": "Testperson-nl",
            "last_name": "Approved",
            "address1": "Kraanspoor",
            "house_number": "39C",
            "zip_code": "1033 SC",
            "city": "Amsterdam",
            "country": "NL",
            "country_name": null,
            "phone1": "0208500500",
            "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": "NL"
                        },
                        {
                            "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"
    }
}

POST -/orders

{
    "type": "redirect",
    "gateway": "EINVOICE",
    "order_id": "my-order-id-1",
    "currency": "EUR",
    "amount": "26000",
    "description": "Test Order Description",
    "manual": "false",
    "gateway_info": {
        "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": ""
    },
    "plugin": {
        "shop": "ApiTestTool",
        "plugin_version": "1.0.0",
        "shop_version": "1",
        "partner": "partner",
        "shop_root_url": "http://multisafepay.com"
    },
    "customer": {
        "locale": "nl_NL",
        "ip_address": "89.20.162.110",
        "forwarded_ip": "",
        "first_name": "Testperson-nl",
        "last_name": "Approved",
        "address1": "Kraanspoor",
        "house_number": "39",
        "zip_code": "1033 SC",
        "city": "Amsterdam",
        "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": "Kraanspoor",
        "house_number": "39",
        "zip_code": "1033 SC",
        "city": "Amsterdam",
        "country": "NL",
        "phone": "02085000500",
        "email": "[email protected]"
    },
    "shopping_cart": {
        "items": [
            {
                "name": "Geometric Candle Holders",
                "description": "",
                "unit_price": "90",
                "quantity": "2",
                "merchant_item_id": "11111",
                "tax_table_selector": "none",
                "weight": {
                    "unit": "KG",
                    "value": "12"
                }
            },
            {
                "name": "Nice apple",
                "description": "",
                "unit_price": "35",
                "quantity": "2",
                "merchant_item_id": "666666",
                "tax_table_selector": "none",
                "weight": {
                    "unit": "KG",
                    "value": "20"
                }
            },
            {
                "name": "Flat Rate - Fixed",
                "description": "Shipping",
                "unit_price": "10",
                "quantity": "1",
                "merchant_item_id": "123456",
                "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": "NL"
                        },
                        {
                            "rate": "0.08375",
                            "country": "NL"
                        }
                    ]
                }
            ]
        }
    }
}

JSON response

{
    "success": true,
    "data": {
        "order_id": "my-order-id-1",
        "payment_url": "https://payv2.multisafepay.com/connect/82v6HsoQhaR823uIZ7hexDMwQyielzLrdox/?lang=nl_NL"
    }
}

E-invoicing

Direct - E-invoicing

Creates a direct 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	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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.
email	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

Read more about E-Invoicing on our documentation page.

Redirect - E-invoicing

Creates a redirect 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	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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.
email	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

Read more about E-Invoicing on our documentation page.

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"
    }
}

EPS

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	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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

Read more about EPS on our documentation page.

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"
    }
}

Giropay

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:	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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

Read more about Giropay on our documentation page.

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": "80.123.456.789",
        "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"
  }
}

Gift card

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	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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. In the event that the transaction is marked with the status uncleared, the customer will also be redirected to this page of the webshop. The uncleared status will not be passed on to the customer who will experience the payment as successful at all times.
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
email	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
Beautyandwellness	BEAUTYWELL
Bloemencadeaukaart	BLOEMENCAD
Boekenbon	BOEKENBON
Degrotespeelgoedwinkel	DEGROTESPL
Fashioncheque	FASHIONCHQ
Fashiongiftcard	FASHIONGFT
Fietsenbon	FIETSENBON
Gezondheidsbon	GEZONDHEID
Givacard	Branded gift cards will provide a gateway name upon release of the personilized gift card by our development team.
Goodcard	GOODCARD
Nationale bioscoopbon	NATNLBIOSC
Nationaletuinbon	NATNLETUIN
Parfumcadeaukaart	PARFUMCADE
Sportenfit	SPORTENFIT
Vuur & rook gift card	VRGIFTCARD
VVV Cadeaukaart	VVVGIFTCRD
Webshopgiftcard	WEBSHOPGFT
Wijncadeau	WIJNCADEAU
Yourgift	YOURGIFT

Read more about the gift cards we offer on our documentation page.

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"
    }
}

iDEAL QR

Please note: If you would like to test iDEAL QR, please note that this will only work in a Live environment. The Testing environment is currently not available.

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	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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.

Read more about iDEAL QR on our documentation page.

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"
    }
}

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": {
    "amount": 1000,
    "amount_refunded": 0,
    "costs": [
      {
        "amount": 0.49,
        "description": "0.49 For iDEAL Transactions",
        "transaction_id": 345498930,
        "type": "SYSTEM"
      }
    ],
    "created": "2020-01-14T12:08:43",
    "currency": "EUR",
    "custom_info": {
      "custom_1": null,
      "custom_2": null,
      "custom_3": null
    },
    "customer": {
      "address1": null,
      "address2": null,
      "city": null,
      "country": null,
      "country_name": null,
      "email": "",
      "first_name": null,
      "house_number": null,
      "last_name": null,
      "locale": "en_US",
      "phone1": null,
      "phone2": "",
      "state": null,
      "zip_code": null
    },
    "description": "product description",
    "fastcheckout": "NO",
    "financial_status": "initialized",
    "items": null,
    "modified": "2020-01-14T12:08:43",
    "order_id": "apitool_504957",
    "payment_details": {
      "account_holder_name": null,
      "account_iban": "https://www.abnamro.nl/en/ideal-betalen/index.html?randomizedstring=8641247395&trxid=1150001181473373",
      "account_id": null,
      "external_transaction_id": "1150001181473373",
      "issuer_id": "0031",
      "recurring_id": null,
      "recurring_model": null,
      "type": "IDEAL"
    },
    "payment_methods": [
      {
        "amount": 1000,
        "currency": "EUR",
        "description": "product description",
        "external_transaction_id": "1150001181473373",
        "payment_description": "iDEAL",
        "status": "initialized",
        "type": "IDEAL"
      }
    ],
    "reason": "",
    "reason_code": "",
    "related_transactions": null,
    "status": "initialized",
    "transaction_id": 326349791,
    "var1": null,
    "var2": null,
    "var3": null,
    "payment_url": "https://www.abnamro.nl/en/ideal-betalen/index.html?randomizedstring=8641247395&trxid=1150001181473373"
  }
}

iDEAL

Redirect - iDEAL

In the case of a Redirect transaction, the consumer will be sent to the MultiSafepay payment page where it will then be possible to select iDEAL as a payment method.

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	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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.

Direct - iDEAL

In the case of a Direct transaction, the consumer has to choose iDEAL and the issuing bank on the checkout page. Once selected, they will be directed to the payment page of the issuing bank, thus skipping the MultiSafepay payment page.

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

Read more about iDEAL on our documentation page.

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": "be_BE"
    }
}

JSON Response

{
  "success": true,
  "data": {
    "transaction_id": 260468043,
    "order_id": "my-order-id-1",
    "created": "2019-03-11T14:35:13",
    "currency": "EUR",
    "amount": 1000,
    "description": "Test Order Description",
    "items": null,
    "amount_refunded": 0,
    "status": "initialized",
    "financial_status": "initialized",
    "reason": "",
    "reason_code": "",
    "fastcheckout": "NO",
    "modified": "2019-03-11T14:35:13",
    "customer": {
      "locale": "be_BE",
      "first_name": "Testperson-nl",
      "last_name": "Approved",
      "address1": "Kraanspoor",
      "house_number": "39C",
      "zip_code": "1033 SC",
      "city": "Amsterdam",
      "country": "NL",
      "country_name": "Netherlands",
      "phone1": "0208500500",
      "email": "[email protected]",
    },
    "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": ""
    },
    "costs": [
      {
        "transaction_id": 279925866,
        "description": "",
        "type": "SYSTEM",
        "amount": 
      }
    ],
    "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"
  }
}

POST -/orders

{
    "type": "redirect",
    "order_id": "my-order-id-1",
    "currency": "EUR",
    "amount": 1000,
    "gateway": "INGHOME",
    "description": "product 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"
    }
}

JSON Response

{
  "success": true,
  "data": {
    "order_id": "my-order-id-1",
    "payment_url": "https://payv2.multisafepay.com/connect/12RxGzQe6fsi23ml9WkS9lUfwJxo8yYVWgn/?lang=en_US"
  }
}

ING Home’Pay

Direct

All parameters shown are required field(s) for an ING Home’Pay direct transaction.

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	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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.

Read more about ING Home’Pay on our documentation page.

Redirect

All parameters shown are required field(s) for an ING Home’Pay redirect transaction.

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	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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

Read more about ING Home’Pay on our documentation page.

POST - /orders

{
    "type": "redirect",
    "gateway": "KLARNA",
    "order_id": "my-order-id-1",
    "currency": "EUR",
    "amount": "26000",
    "description": "Test Order Description",
    "items": "",
    "manual": "false",
    "gateway_info": {
        "birthday": "1970-07-10",
        "gender": "male",
        "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": "nl_NL",
        "ip_address": "31.148.195.10",
        "forwarded_ip": "",
        "first_name": "Testperson-nl",
        "last_name": "Approved",
        "address1": "Kraanspoor",
        "house_number": "39",
        "zip_code": "1033 SC",
        "city": "Amsterdam",
        "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": "Kraanspoor",
        "house_number": "39",
        "zip_code": "1033 SC",
        "city": "Amsterdam",
        "country": "NL",
        "phone": "0208500500",
        "email": "[email protected]"
    },
    "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": "NL"
                        },
                        {
                            "rate": "0.08375",
                            "country": "NL"
                        }
                    ]
                }
            ]
        }
    }
}

JSON Response

{
  "success": true,
  "data": {
    "order_id": "my-order-id-1",
    "payment_url": "https://payv2.multisafepay.com/connect/13sEMtA491h823BLOx5Upa9H9XGEpYeUEg9/?lang=en_US"
  }
}

POST - /orders

{
    "type": "redirect",
    "gateway": "KLARNA",
    "order_id": "my-order-id-1",
    "currency": "EUR",
    "amount": "31500",
    "description": "Test Order Description",
    "manual": "false",
    "gateway_info": {
        "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": ""
    },
    "plugin": {
        "shop": "ApiTestTool",
        "plugin_version": "1.0.0",
        "shop_version": "1",
        "partner": "partner",
        "shop_root_url": "http://multisafepay.com"
    },
    "customer": {
        "locale": "nl_NL",
        "ip_address": "89.20.162.110",
        "forwarded_ip": "",
        "first_name": "Testperson-nl",
        "last_name": "Approved",
        "address1": "Kraanspoor",
        "house_number": "39",
        "zip_code": "1033 SC",
        "city": "Amsterdam",
        "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": "Kraanspoor",
        "house_number": "39",
        "zip_code": "1033 SC",
        "city": "Amsterdam",
        "country": "NL",
        "phone": "0208500500",
        "email": "[email protected]"
    },
    "shopping_cart": {
        "items": [
            {
                "name": "Geometric Candle Holders",
                "description": "",
                "unit_price": "90",
                "quantity": "3",
                "merchant_item_id": "1111111",
                "tax_table_selector": "none",
                "weight": {
                    "unit": "KG",
                    "value": "12"
                }
            },
            {
                "name": "Nice apple",
                "description": "",
                "unit_price": "35",
                "quantity": "1",
                "merchant_item_id": "222222",
                "tax_table_selector": "none",
                "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": "NL"
                        },
                        {
                            "rate": "0.08375",
                            "country": "NL"
                        }
                    ]
                }
            ]
        }
    }
}

JSON Response

{
    "success": true,
    "data": {
        "order_id": "my-order-id-1",
        "payment_url": "https://payv2.multisafepay.com/connect/12oyNt6GDQS823vwlxIbfBe45H8HYqoQWAi/?lang=nl_NL"
    }
}

Klarna

Direct - Klarna

Creates a Klarna order to be paid after delivery

Klarna is available as both a direct and redirect request. However, Klarna Payments (the new environment of Klarna) is only available as a redirect request. The direct request is no longer supported by Klarna Payments.

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	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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
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.
email	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

Read more about Klarna on our documentation page.

Redirect - Klarna (Klarna Payments)

Creates a Klarna Payments Redirect order to be paid after delivery

Please note this request is for Klarna Payments. This request can only be processed as a redirect request.

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	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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
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.
email	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

Read more about Klarna on our documentation page.

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"
    }
}

POST - /orders

{
    "type": "direct",
    "order_id": "my-order-id-1",
    "gateway": "KBC",
    "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",
        "close_window": ""
    },
    "customer": {
        "locale": "nl_NL",
        "ip_address": "89.20.162.110",
        "forwarded_ip": "",
        "first_name": "Testperson-nl",
        "last_name": "Approved",
        "address1": "Kraanspoor",
        "house_number": "39C",
        "zip_code": "1033 SC",
        "city": "Amsterdam",
        "country": "NL",
        "phone": "020 8500 500",
        "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"
    }
}

JSON Repsonse

{
  "success": true,
  "data": {
    "amount": 1000,
    "amount_refunded": 0,
    "costs": [
      {
        "amount":,
        "description": "",
        "transaction_id": 344230330,
        "type": "SYSTEM"
      },
      {
        "amount":,
        "description": "",
        "transaction_id": 344230331,
        "type": "SYSTEM"
      }
    ],
    "created": "2019-03-08T10:15:37",
    "currency": "EUR",
    "custom_info": {
      "custom_1": null,
      "custom_2": null,
      "custom_3": null
    },
    "customer": {
      "address1": "Kraanspoor",
      "address2": null,
      "city": "Amsterdam",
      "country": "NL",
      "country_name": null,
      "email": "[email protected]",
      "first_name": "Testperson-nl",
      "house_number": 39C,
      "last_name": "Approved",
      "locale": "nl_NL",
      "phone1": "020 8500 500",
      "zip_code": "1033 SC"
    },
    "description": "Test Order Description",
    "fastcheckout": "NO",
    "financial_status": "initialized",
    "items": null,
    "modified": "2019-03-08T10:15:37",
    "order_id": "my-order-id-1",
    "payment_details": {
      "account_holder_name": null,
      "account_id": null,
      "external_transaction_id": 325062361,
      "recurring_id": null,
      "recurring_model": null,
      "type": "KBC"
    },
    "payment_methods": [
      {
        "amount": 1000,
        "currency": "EUR",
        "description": "Test Order Description",
        "external_transaction_id": 325062361,
        "payment_description": "KBC",
        "status": "initialized",
        "type": "KBC"
      }
    ],
    "reason": "",
    "reason_code": "",
    "related_transactions": null,
    "status": "initialized",
    "transaction_id": 325062361,
    "payment_url": "https://www.kbc.be/olpayment?langWebSite=N&olpId=S132&olpCtx=%2FH8s4RM8GN%2FSKLOcUoTBBPus%2BWBbXCz9ChR12y5ozVDe8Rc70DjFQNQy2TaiSnTOEQkziFEQmgQy%2BHDxrqqzB%2F8I1yk5zE0%"
  }
}

KBC

Redirect

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	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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.

Read more about KBC on our documentation page.

Direct

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	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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.

Read more about KBC on our documentation page.

POST - /orders

{
    "type": "redirect",
    "gateway": "PAYAFTER",
    "order_id": "my-order-id-1",
    "currency": "EUR",
    "amount": "26000",
    "description": "Test Order Description",
    "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": "Kraanspoor",
        "house_number": "39",
        "zip_code": "1033 SC",
        "city": "Amsterdam",
        "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": "Kraanspoor",
        "house_number": "39",
        "zip_code": "1033 SC",
        "city": "Amsterdam",
        "country": "NL",
        "phone": "020 8500 500",
        "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": {
    "order_id": "apitool_2710316",
    "payment_url": "https://payv2.multisafepay.com/connect/820UDg9zumqA13QovrRq1YVgpdTVxAlpJAP/?lang=nl_NL"
  }
}

POST - /orders

{
    "type": "direct",
    "gateway": "PAYAFTER",
    "order_id": "my-order-id-1",
    "currency": "EUR",
    "amount": "26000",
    "description": "Test Order Description",
    "manual": "false",
    "gateway_info": {
        "birthday": "1979-02-22",
        "bank_account": "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": ""
    },
    "plugin": {
        "shop": "ApiTestTool",
        "plugin_version": "1.0.0",
        "shop_version": "1",
        "partner": "partner",
        "shop_root_url": "http://multisafepay.com"
    },
    "customer": {
        "locale": "nl_NL",
        "ip_address": "89.20.162.110",
        "forwarded_ip": "",
        "first_name": "Testperson-nl",
        "last_name": "Approved",
        "address1": "Kraanspoor",
        "house_number": "39C",
        "zip_code": "1033 SC",
        "city": "Amsterdam",
        "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": "Kraanspoor",
        "house_number": "39C",
        "zip_code": "1033 SC",
        "city": "Amsterdam",
        "country": "NL",
        "phone": "0208500500",
        "email": "[email protected]"
    },
    "shopping_cart": {
        "items": [
            {
                "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": "2",
                "merchant_item_id": "333333",
                "tax_table_selector": "none",
                "weight": {
                    "unit": "KG",
                    "value": "20"
                }
            },
            {
                "name": "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": "US"
                        }
                    ]
                }
            ]
        }
    }
}

JSON Response

{
  "success": true,
  "data": {
    "amount": 26000,
    "amount_refunded": 0,
    "checkout_options": {
      "alternate": [
        {
          "name": "BTW21",
          "rules": [
            {
              "country": "",
              "rate": "0.21"
            }
          ],
          "standalone": true
        },
        {
          "name": "BTW6",
          "rules": [
            {
              "country": "",
              "rate": "0.06"
            }
          ],
          "standalone": true
        },
        {
          "name": "BTW0",
          "rules": [
            {
              "country": "",
              "rate": "0.00"
            }
          ],
          "standalone": true
        },
        {
          "name": "0.0000",
          "rules": [
            {
              "country": "",
              "rate": "0.00"
            }
          ],
          "standalone": ""
        },
        {
          "name": "0.0000",
          "rules": [
            {
              "country": "",
              "rate": "0.00"
            }
          ],
          "standalone": ""
        },
        {
          "name": "FEE",
          "rules": [
            {
              "country": "",
              "rate": "0.00"
            }
          ],
          "standalone": ""
        },
        {
          "name": "none",
          "rules": [
            {
              "country": "",
              "rate": "0.00"
            }
          ],
          "standalone": ""
        },
        {
          "name": 2,
          "rules": [
            {
              "country": "NL",
              "rate": "0.0825"
            },
            {
              "country": "NL",
              "rate": "0.08375"
            }
          ],
          "standalone": true
        }
      ],
      "default": {
        "rate": 0.21,
        "shipping_taxed": true
      }
    },
    "costs": [
      {
        "amount":,
        "description": "",
        "transaction_id": 2045938,
        "type": "SYSTEM"
      },
      {
        "amount":,
        "description": "",
        "transaction_id": 2045939,
        "type": "SYSTEM"
      }
    ],
    "created": "2019-01-12T13:55:38",
    "currency": "EUR",
    "custom_info": {
      "custom_1": null,
      "custom_2": null,
      "custom_3": null
    },
    "customer": {
      "address1": "Kraanspoor",
      "city": "Amsterdam",
      "country": "NL",
      "country_name": null,
      "email": "[email protected]",
      "first_name": "Testperson-nl",
      "house_number": "39C",
      "last_name": "Approved",
      "locale": "nl_NL",
      "phone1": "0208500500",
      "phone2": "",
      "zip_code": "1033 SC"
    },
    "description": "Test Order Description",
    "fastcheckout": "NO",
    "financial_status": "uncleared",
    "items": ""
    "modified": "2019-01-12T13:55:38",
    "order_adjustment": {
      "total_adjustment": "0.00",
      "total_tax": "0.00"
    },
    "order_id": "my-order-id-1",
    "order_total": "260.00",
    "payment_details": {
      "account_holder_name": 417164300,
      "account_id": "1980-01-30",
      "external_transaction_id": null,
      "invoice_url": "https://payv2.multisafepay.com/orders/e61d7dbbfd48053ee5873553707986a5",
      "recurring_id": null,
      "recurring_model": null,
      "type": "PAYAFTER"
    },
    "payment_methods": [
      {
        "account_holder_name": 417164300,
        "account_id": "1979-01-30",
        "amount": 26000,
        "currency": "EUR",
        "description": "Test Order Description",
        "payment_description": "Pay after delivery",
        "status": "uncleared",
        "type": "PAYAFTER"
      }
    ],
    "reason": "",
    "reason_code": "",
    "related_transactions": null,
    "shopping_cart": {
      "items": [
        {
          "cashback": "",
          "currency": "EUR",
          "description": "",
          "image": "",
          "merchant_item_id": 111111,
          "name": "Geometric Candle Holders",
          "options": [],
          "product_url": "",
          "quantity": 2,
          "tax_table_selector": "none",
          "unit_price": "90.00",
          "weight": {
            "unit": "KG",
            "value": 12
          }
        },
        {
          "cashback": "",
          "currency": "EUR",
          "description": "",
          "image": "",
          "merchant_item_id": 333333,
          "name": "Nice apple",
          "options": [],
          "product_url": "",
          "quantity": 2,
          "tax_table_selector": "none",
          "unit_price": "35.00",
          "weight": {
            "unit": "KG",
            "value": 20
          }
        },
        {
          "cashback": "",
          "currency": "EUR",
          "description": "Shipping",
          "image": "",
          "merchant_item_id": "msp-shipping",
          "name": "Flat Rate - Fixed",
          "options": [],
          "product_url": "",
          "quantity": 1,
          "tax_table_selector": "none",
          "unit_price": "10.00",
          "weight": {
            "unit": "KG",
            "value": 0
          }
        }
      ]
    },
    "status": "uncleared",
    "transaction_id": 4022655,
    "payment_url": " https://payv2.multisafepay.com/connect/99wi0OTuiCaTY2nwEiEOybWpVx8MNwrJ75c/?lang=en_US",
    "cancel_url": " http://www.example.com/client/notification?type=cancel&transactionid=apitool"
  }
}

Pay After Delivery

Redirect - Pay After Delivery

Creates a redirect request 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	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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.
email	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

Read more about Pay After Delivery on our documentation page.

Direct - Pay After Delivery

Creates a direct request 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	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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.
email	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

Read more about Pay After Delivery on our documentation page.

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"
    }
}

POST - /orders

{
    "type": "direct",
    "order_id": "my-order-id-1",
    "gateway": "PAYPAL",
    "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",
        "close_window": ""
    },
    "customer": {
        "locale": "nl_NL",
        "ip_address": "89.20.162.110",
        "forwarded_ip": "",
        "first_name": "Testperson-nl",
        "last_name": "Approved",
        "address1": "Kraanspoor",
        "house_number": "39C",
        "zip_code": "1033 SC",
        "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"
    }
}

JSON Response

{
  "success": true,
  "data": {
    "amount": 1000,
    "amount_refunded": 0,
    "costs": [],
    "created": "2020-01-30T11:16:11",
    "currency": "EUR",
    "custom_info": {
      "custom_1": null,
      "custom_2": null,
      "custom_3": null
    },
    "customer": {
      "address1": "Kraanspoor",
      "address2": null,
      "city": "Amsterdam",
      "country": "NL",
      "country_name": null,
      "email": "[email protected]",
      "first_name": "Testperson-nl",
      "house_number": "39C",
      "last_name": "Approved",
      "locale": "nl_NL",
      "phone1": "0208500500",
      "phone2": "",
      "state": null,
      "zip_code": "1033SC"
    },
    "description": "Test Order Description",
    "fastcheckout": "NO",
    "financial_status": "initialized",
    "items": null,
    "modified": "2020-01-30T11:16:11",
    "order_id": "my-order-id-1",
    "payment_details": {
      "account_holder_name": "Test-person-nl",
      "account_id": "https://www.paypal.com/cgi-bin/webscr?cmdmsp=_express-checkout&token=EC-8K013819T00365502LLL-msp",
      "external_transaction_id": "8K013819T00365502LLL",
      "paypal_eligibility": "",
      "recurring_id": null,
      "recurring_model": null,
      "type": "PAYPAL"
    },
    "payment_methods": [
      {
        "account_holder_name": "Test-person-nl",
        "account_id": "https://www.paypal.com/cgi-bin/webscr?cmdmsp=_express-checkout&token=EC-8K013819T00365502LLL-msp",
        "amount": 1000,
        "currency": "EUR",
        "description": "Test Order Description",
        "external_transaction_id": "EC-8K013819T00365502L",
        "payment_description": "PayPal",
        "status": "initialized",
        "type": "PAYPAL"
      }
    ],
    "reason": "",
    "reason_code": "",
    "related_transactions": null,
    "status": "initialized",
    "transaction_id": 329843232,
    "payment_url": "https://www.paypal.com/cgi-bin/webscr?cmdmsp=_express-checkout&token=EC-8K013819T00365502LLL-msp"
  }
}

PayPal

Redirect

All parameters shown are required field(s) for a PayPal redirect transaction.

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:	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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.

Read more about PayPal on our documentation page.

Direct

All parameters shown are required field(s) for a PayPal direct transaction.

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:	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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.

Read more about PayPal on our documentation page.

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": "Kraanspoor",
        "house_number": "39",
        "zip_code": "1033 SC",
        "city": "Amsterdam",
        "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"
    }
}

Santander Betaalplan

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	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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).

Read more about Betaalplan on our docuemntation page.

POST - /orders

{
    "type": "redirect",
    "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": "de_DE"
    }
}

JSON Response

{
    "success": true,
    "data": {
        "order_id": "my-order-id-1",
        "payment_url": "https://payv2.multisafepay.com/connect/13oElUaESR7YS2b4gUJV9oI4tUXeb1mj1D8/?lang=de_DE"
    }
}

POST - /orders

{
    "type": "direct",
    "order_id": "my-order-id-1",
    "gateway": "DIRECTBANK",
    "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",
        "close_window": ""
    },
    "customer": {
        "locale": "de_DE",
        "ip_address": "89.20.162.110",
        "forwarded_ip": "",
        "first_name": "Testperson-nl",
        "last_name": "Approved",
        "address1": "Kraanspoor",
        "house_number": "39C",
        "zip_code": "1033 SC",
        "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"
    }
}

JSON Response

{
  "success": true,
  "data": {
    "amount": 9743,
    "amount_refunded": 0,
    "costs": [
      {
        "amount":,
        "description": "",
        "transaction_id": 348956887,
        "type": "SYSTEM"
      },
      {
        "amount":,
        "description": "",
        "transaction_id": 348956888,
        "type": "SYSTEM"
      }
    ],
    "created": "2020-01-30T10:43:39",
    "currency": "EUR",
    "custom_info": {
      "custom_1": null,
      "custom_2": null,
      "custom_3": null
    },
    "customer": {
      "address1": "Kraanspoor",
      "address2": null,
      "city": "Amsterdam",
      "country": "NL",
      "country_name": null,
      "email": "[email protected]",
      "first_name": "Testperson-nl",
      "house_number": "39C",
      "last_name": "Approved",
      "locale": "de_DE",
      "phone1": "0208500500",
      "zip_code": "1033 SC"
    },
    "description": "Test Order Description",
    "fastcheckout": "NO",
    "financial_status": "initialized",
    "items": null,
    "modified": "2020-01-30T10:43:39",
    "order_id": "my-order-id-1",
    "payment_details": {
      "account_holder_name": null,
      "account_id": 10071970,
      "external_transaction_id": null,
      "recurring_id": null,
      "recurring_model": null,
      "type": "DIRECTBANK"
    },
    "payment_methods": [
      {
        "account_id": 10071970,
        "amount": 9743,
        "currency": "EUR",
        "description": "Test Order Description",
        "payment_description": "SOFORT Banking",
        "status": "initialized",
        "type": "DIRECTBANK"
      }
    ],
    "reason": "",
    "reason_code": "",
    "related_transactions": null,
    "status": "initialized",
    "transaction_id": 329835554,
    "payment_url": "https://payv2.multisafepay.com/connect/99wi0OTuiCaTY2nwEiEOybWpVx8MNwrJ75c/?lang=de_DE",
    "cancel_url": "http://www.example.com/client/notification?type=cancel"
  }
}

SOFORT

Redirect

All parameters shown are required field(s) for a SOFORT redirect transaction.

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:	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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.

Read more about SOFORT Banking on our documentation page.

Direct

All parameters shown are required field(s) for a SOFORT direct transaction.

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:	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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.

Read more about SOFORT Banking on our documentation page.

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"
  }
}

Trustly

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	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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. In the event that the transaction is marked with the status uncleared, the customer will also be redirected to this page of the webshop. The uncleared status will not be passed on to the customer who will experience the payment as successful at all times.
cancel_url	string	Customer will be redirected to this page after a failed payment.
customer	object	Contains the personal information of the customer.

Read more about Trustly on our documentation page.

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"
  }
}

TrustPay

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	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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. In the event that the transaction is marked with the status uncleared, the customer will also be redirected to this page of the webshop. The uncleared status will not be passed on to the customer who will experience the payment as successful at all times.
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
email	string	Customer’s provided email address. Used to send Second Chance emails, in fraud checks and the sending bank transfer email.

Read more about TrustPay on our documentation page.

POST - /orders

{
    "type": "redirect",
    "order_id": "my-order-id-1",
    "gateway": "DIRDEB",
    "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": "nl_NL"
    }
}

JSON Response

{
    "success": true,
    "data": {
        "order_id": "my-order-id-1",
        "payment_url": "https://payv2.multisafepay.com/connect/13oElUaESR7YS2b4gUJV9oI4tUXeb1mj1D8/?lang=nl_NL"
    }
}

POST - /orders

{
    "type": "direct",
    "order_id": "my-order-id-1",
    "gateway": "DIRDEB",
    "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": "nl_NL",
        "ip_address": "31.148.195.10",
        "forwarded_ip": ""
    },
    "gateway_info": {
        "account_id": "NL87ABNA0000000001",
        "account_holder_name": "J Janse",
        "account_holder_iban": "NL87ABNA0000000001",
        "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",
    "items": "",
    "amount_refunded": 0,
    "status": "initialized",
    "financial_status": "initialized",
    "reason": "",
    "reason_code": "",
    "fastcheckout": "NO",
    "modified": "2019-03-08T09:23:46",
    "customer": {
      "locale": "nl_NL",
      "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",
    },
    "costs": [
      {
        "transaction_id": 279354751,
        "description": "0.3 For SEPA 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"
  }
}

SEPA Direct Debit

Redirect

When submitting a SEPA 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: IDEAL.
order_id	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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.

Direct

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	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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_iban	string	IBAN 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

Read more about SEPA Direct Debit on our docuemntation page.

POST - /orders

{
    "type": "redirect",
    "order_id": "my-order-id-1",
    "gateway": "MAESTRO",
    "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": "nl_NL",
    "ip_address": "127.0.0.1"
  }
}

JSON Response

{
  "success": true,
  "data": {
    "order_id": "my-order-id-1",
    "payment_url": "https://payv2.multisafepay.com/connect/13oElUaESR7YS2b4gUJV9oI4tUXeb1mj1D8/?lang=nl_NL"
  }
}

Maestro

All parameters shown are required field(s) for a Maestro Redirect transaction.

Parameter	Type	Description
type	string	Specifies the payment flow for the checkout process. Options: redirect.
gateway	string	Fixed value: MAESTRO
order_id	string\|integer	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
currency	string	The currency ISO-4217 you want the customer to pay with.
amount	integer	The amount (in cents) that the customer has 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. In the event that the transaction is marked with the status uncleared, the customer will also be redirected to the thank-you page of the webshop. The uncleared status will not be passed on to the customer who will experience the payment as successful at all times.
cancel_url	string	Customer will be redirected to this page after a failed payment.

Read more about Maestro on our documentation page.

POST - /orders

{
    "type": "redirect",
    "order_id": "my-order-id-1",
    "gateway": "MASTERCARD",
    "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": "nl_NL",
    "ip_address": "127.0.0.1"
  }
}

JSON Response

{
  "success": true,
  "data": {
    "order_id": "my-order-id-1",
    "payment_url": "https://payv2.multisafepay.com/connect/13oElUaESR7YS2b4gUJV9oI4tUXeb1mj1D8/?lang=nl_NL"
  }
}

Mastercard

All parameters shown are required field(s) for A Mastercard redirect transaction.

Parameter	Type	Description
type	string	Specifies the payment flow for the checkout process. Options: redirect.
gateway	string	Fixed value: MASTERCARD
order_id	string\|integer	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
currency	string	The currency ISO-4217 you want the customer to pay with.
amount	integer	The amount (in cents) that the customer has 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. In the event that the transaction is marked with the status uncleared, the customer will also be redirected to the thank-you page of the webshop. The uncleared status will not be passed on to the customer who will experience the payment as successful at all times.
cancel_url	string	Customer will be redirected to this page after a failed payment.

Read more about Mastercard on our documentation page.

POST - /orders

{
    "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": "nl_NL",
    "ip_address": "127.0.0.1"
  }
}

JSON Response

{
  "success": true,
  "data": {
    "order_id": "my-order-id-1",
    "payment_url": "https://payv2.multisafepay.com/connect/13oElUaESR7YS2b4gUJV9oI4tUXeb1mj1D8/?lang=nl_NL"
  }
}

Visa

All parameters shown are required field(s) for a Visa Redirect transaction.

Parameter	Type	Description
type	string	Specifies the payment flow for the checkout process. Options: redirect.
gateway	string	Fixed value: VISA
order_id	string\|integer	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
currency	string	The currency ISO-4217 you want the customer to pay with.
amount	integer	The amount (in cents) that the customer has 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. In the event that the transaction is marked with the status uncleared, the customer will also be redirected to the thank-you page of the webshop. The uncleared status will not be passed on to the customer who will experience the payment as successful at all times.
cancel_url	string	Customer will be redirected to this page after a failed payment.

Read more about Visa on our documentation page.

POST - /orders

{
    "type": "redirect",
    "order_id": "my-order-id-1",
    "gateway": "DBRTP",
    "currency": "EUR",
    "amount": "9743",
    "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",
        "close_window": ""
    },

JSON Response

{
  "success": true,
  "data": {
    "order_id": "my-order-id-1",
    "payment_url": "https://payv2.multisafepay.com/connect/12SV72okI6zR23ofq5gdEnaFYZ4qLZ3aFLj/?lang=nl_NL"
  }
}

POST - /orders

{
    {
    "type": "direct",
    "order_id": "my-order-id-1",
    "gateway": "DBRTP",
    "currency": "EUR",
    "amount": "9743",
    "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",
        "close_window": ""
    },

JSON Response

{
  "success": true,
  "data": {
    "amount": 9743,
    "amount_refunded": 0,
    "costs": [
      {
        "amount":,
        "description": "",
        "transaction_id": 36166179527,
        "type": "SYSTEM"
      }
    ],
    "created": "2020-03-25T12:07:00",
    "currency": "EUR",
    "custom_info": {
      "custom_1": null,
      "custom_2": null,
      "custom_3": null
    },
    "customer": {
      "address1": "Kraanspoor",
      "city": "Amsterdam",
      "country": "NL",
      "email": "[email protected]",
      "first_name": "Testperson-nl",
      "house_number": "39C",
      "last_name": "Approved",
      "locale": "nl_NL",
      "phone1": "0208500500",
      "zip_code": "1033 SC"
    },
    "description": "Test Order Description",
    "fastcheckout": "NO",
    "financial_status": "initialized",
    "items": null,
    "modified": "2020-03-25T12:07:00",
    "order_id": "my-order-id-1",
    "payment_details": {
      "account_holder_name": null,
      "account_id": null,
      "external_transaction_id": "P-26660200325-0935",
      "recurring_id": null,
      "recurring_model": null,
      "type": "DBRTP"
    },
    "payment_methods": [
      {
        "amount": 9743,
        "currency": "EUR",
        "description": "Test Order Description",
        "external_transaction_id": "P-26660200325-0935",
        "payment_description": "Direct Bank Transfer",
        "status": "initialized",
        "type": "DBRTP"
      }
    ],
    "reason": "",
    "reason_code": "",
    "related_transactions": null,
    "status": "initialized",
    "transaction_id": 36166179527,
    "payment_url": "https://pushpayments.db.com/flow/eyJwYXlsb2FkIjp7ImlwaSI6IjE2QjIwREREMjE1NjE0QTc2Rjg0OTMwMDV="
  }
}

Direct Bank Transfer

All parameters shown are required field(s) for a Direct Bank Transfer Redirect transaction:

Parameter	Type	Description
type	string	Specifies the payment flow for the checkout process. Options: Redirect.
gateway	string	The payment gateway does not need to be specified.
order_id	string\|integer	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
currency	string	The currency ISO-4217 you want the customer to pay with.
amount	integer	The amount (in cents) that the customer has 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. In the event that the transaction is marked with the status uncleared, the customer will also be redirected to the thank-you page of the webshop. The uncleared status will not be passed on to the customer who will experience the payment as successful at all times.
cancel_url	string	Customer will be redirected to this page after a failed payment.

Direct Bank Transfer Direct

All parameters shown are required field(s) for a Apple Pay Direct transaction.

Parameter	Type	Description
type	string	Specifies the payment flow for the checkout process. Options: Direct.
payment_options	object

Read more about Direct Bank Transfer on our documentation page.

POST - /orders/{order_id}/refunds

{
    "currency": "EUR",
    "amount": "8",
    "description": "Your refund description"
}

JSON Response

{
  "success": true,
  "data": {
    "transaction_id": 3326965,
    "refund_id": 3326969
  }
}

Create a refund

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.

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"
                }
            }
        ]
    }
}

Refund with shopping cart

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.

Klarna needs negative unit prices, whereas Pay After Delivery orders need negative quantities!!

Parameter	Type	Description
checkout_data	object	Contains the original shopping cart + copied items to be refunded.

GET - /categories

JSON Response

{
    "success": true,
    "data": [
        {
            "code": 999,
            "description": "Adult"
        },
        {
            "code": 106,
            "description": "Child and toys"
        }
    ]
}

Chargeback

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.

"locale": "nl_NL",

"ip_address": "31.148.195.10",

"forwarded_ip": "",

"first_name": "customer's first name",

"last_name": "customer's last name",

"address1": "Kraanspoor",

"address2": "customer's address",

"house_number": "39",

"zip_code": "1033SC",

"city": "Amsterdam",

"country": "Netherlands",

"phone": "0208500500",

"email": "[email protected]",

customer, object

locale

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

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

Parameter	Type	Description
first_name	string	The customer’s first name.

last_name

Parameter	Type	Description
last_name	string	The customer’s last name.

address1

Parameter	Type	Description
address1	string	First line of customer’s provided address.

address2

Parameter	Type	Description
address2	string	Second line of customer’s provided address.

house_number

Parameter	Type	Description
house_number	string	Customer’s provided house number.

zip_code

Parameter	Type	Description
zip_code	string	Customer’s provided zip / postal code.

city

Parameter	Type	Description
city	string	Customer’s provided city.

country

Parameter	Type	Description
country	string	Customer’s provided country code ISO 3166-1

phone

Parameter	Type	Description
phone	string	Customer’s provided phone number.

email

Parameter	Type	Description
email	string	Customer’s provided email address. Used to send Second Chance emails and in fraud checks.

"days_active": 30,

"seconds_active": 60,

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

Parameter	Type	Description
days_active	string	The number of days the payment link will be active for. Default is 30.

Parameter	Type	Description
seconds_active	string	The number of seconds the payment link will be active for. Default is 30 days.

 "second_chance": {
   "send_email": false
},

Second Chance

If the customer didn’t finish the payment, MultiSafepay can send reminders on your behalf.

It is possible to enable/disable the second chance message per transaction. The system uses the following rules:

(*) provided that the conditions above are fulfilled.

Parameter	Type	Description
second_chance	object	When no value is stated, second chance reminders will be sent .
send_email	string	When this parameter is set to false, second chance reminders will not be sent.
send_email	string	When this parameter is set to true, second chance reminders will be sent.

The full documentation can be found in the documentation Second Chance

Tokenization & Recurring Model

Tokenization is a the process of completely removing sensitive data from and companys’ internal network by replacing it with a randomly generated, unique placeholder called a token.

These tokens can be used to process recurring transactions.

This section lists the API calls for different token scenarios and the required parameters.

All parameters shown are required field(s)

POST - /orders

{
        "type": "redirect",
        "gateway": "CREDITCARD",
        "order_id": "my-order-id-1",
        "currency": "EUR",
        "recurring_model": "unscheduled",
        "amount": 10000,
        "description": "Tokenization - ALL - Original unscheduled",
        "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": "85.149.25.196",
                "forwarded_ip": "",
                "first_name": "Testperson-nl",
                "last_name": "Approved",
                "address1": "Kraanspoor",
                "house_number": "39",
                "zip_code": "1033 SC",
                "city": "Amsterdam",
                "country": "NL",
                "birthday": "10071970",
                "gender": "male",
                "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",
                "reference": "AutoQAReference"
        }
}

JSON response

{
    "success": true,
    "data": {
        "order_id": "my-order-id-1",
        "payment_url": "https://payv2.multisafepay.com/connect/13oElUaESR7YS2b4gUJV9oI4tUXeb1mj1D8/?lang=nl_NL"
    }
}

Original Tokenization transaction

This API call allows you to create an original order using a specific recurring model.

MultiSafepay offers the following recurring models: Card on file (COF), Subscription, Unscheduled

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 E.g. CREDITCARD.
order_id	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
currency	string	The currency ISO-4217 you want the customer to pay with.
recurring_model	string	The function of the recurring model e.g. Card on file, Subscription, Unscheduled
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
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

Read our decicated documentation on Tokenization

GET - /orders/{order_id}

JSON Response

{
    "success": true,
    "data": {
        "amount": 10000,
        "amount_refunded": 0,
        "costs": [
            {
                "amount": ,
                "description": "Tokenization Test Order",
                "transaction_id": 767286,
                "type": "SYSTEM"
            }
        ],
        "created": "2019-10-24T13:19:08",
        "currency": "EUR",
        "custom_info": {
            "custom_1": null,
            "custom_2": null,
            "custom_3": null
        },
        "customer": {
            "address1": "Kraanspoor",
            "address2": null,
            "city": "Amsterdam",
            "country": "NL",
            "country_name": null,
            "email": "[email protected]",
            "first_name": "Testperson-nl",
            "house_number": "39",
            "last_name": Approved,
            "locale": "nl_NL",
            "phone1": "0208500500",
            "reference": "AutoQAReference",
            "zip_code": "1033 SC"
        },
        "description": "Tokenization Test Order",
        "fastcheckout": "NO",
        "financial_status": "completed",
        "items": null,
        "modified": "2019-10-24T13:19:08",
        "order_id": "AutoQA-1571915948-481",
        "payment_details": {
            "account_holder_name": "Testperson-nl",
            "account_id": null,
            "card_expiry_date": 1612,
            "external_transaction_id": null,
            "last4": 1111,
            "recurring_id": " azbkvsE0up4",
            "recurring_model": "unscheduled",
            "type": "VISA"
        },
        "payment_methods": [
            {
                "account_holder_name": "Testperson-nl",
                "amount": 10000,
                "card_expiry_date": 4412,
                "currency": "EUR",
                "description": "Tokenization – Test Order",
                "external_transaction_id": 234374824,
                "payment_description": "Visa CreditCards",
                "status": "completed",
                "type": "VISA"
            }
        ],
        "reason": "Successful approval/completion",
        "reason_code": "",
        "related_transactions": null,
        "status": "completed",
        "transaction_id": 2728877,
    }
}

Get order details

This API call allows you to retreive the order details while listing the recurring id and recurring model.

All parameters shown are required field(s)

Parameter	Type	Description
order_id	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.

Read our decicated documentation on Tokenization

POST - /orders

{
    "type": "direct",
    "order_id": "my-order-id-1",
    "currency": "EUR",
    "recurring_id": "azbkvsE0up4",
    "recurring_model": "unscheduled",
    "amount": 1000,
    "description": "Tokenization Generate token transaction",
    "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": {
        "reference": "AutoQAReference"
    }
}

JSON Response

{
    "success": true,
    "data": {
        "amount": 1000,
        "amount_refunded": 0,
        "costs": [
            {
                "amount": 0.6,
                "description": " Tokenization Generate token transaction ",
                "transaction_id": 767288,
                "type": "SYSTEM"
            }
        ],
        "created": "2019-10-24T13:22:45",
        "currency": "EUR",
        "custom_info": {
            "custom_1": null,
            "custom_2": null,
            "custom_3": null
        },
        "customer": {
            "address1": null,
            "address2": null,
            "city": null,
            "country": null,
            "country_name": null,
            "email": "",
            "first_name": null,
            "house_number": null,
            "last_name": null,
            "locale": "nl_NL",
            "phone1": null,
            "phone2": "",
            "reference": "AutoQAReference",
            "state": null,
            "zip_code": null
        },
        "description": "Tokenization - ALL - Trx with previous token with unscheduled model when is disabled",
        "fastcheckout": "NO",
        "financial_status": "completed",
        "items": null,
        "modified": "2019-10-24T13:22:45",
        "order_id": "my-order-id",
        "payment_details": {
            "account_holder_name": "Testperson-nl",
            "account_id": null,
            "card_expiry_date": 1112,
            "external_transaction_id": 929711011483,
            "last4": 1111,
            "recurring_id": "azbkvsE0up4",
            "recurring_model": "unscheduled",
            "type": "VISA"
        },
        "payment_methods": [
            {
                "account_holder_name": "Testperson-nl",
                "amount": 1000,
                "card_expiry_date": 1112,
                "currency": "EUR",
                "description": "Tokenization - ALL - Trx with previous token with unscheduled model when is disabled",
                "external_transaction_id": 929711011483,
                "last4": 0,
                "payment_description": "Visa CreditCards",
                "status": "completed",
                "type": "VISA"
            }
        ],
        "reason": "Successful approval/completion",
        "reason_code": "",
        "related_transactions": null,
        "status": "completed",
        "transaction_id": 2728879,
        "payment_url": " https://payv2.multisafepay.com/connect/99wi0OTuiCaTY2nwEiEOybWpVx8MNwrJ75c/?lang=nl_NL ",
        "cancel_url": " http://www.example.com/client/notification?type=cancel "
    }
}

Create token transaction

This API call allows you to generate a token transaction by using the recurring id and recurring model in the request.

All parameters shown are required field(s)

Parameter	Type	Description
order_id	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
type	string	Specifies the payment flow for the checkout process. Options: direct, redirect, checkout, paymentlink.
order_id	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
currency	string	The currency ISO-4217 you want the customer to pay with.
recurring_id	string	The unique recurring id used for recurring payments.
recurring_model	string	The function of the recurring model e.g. Card on file, Subscription, Unscheduled
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.
accountholder name	string	The customer’s name here if provided in transaction request.
card_expiry_date	string	Card expiry date.
reason	string	Add a short text memo based on the capture reason of the order.

Read our decicated documentation on Tokenization

GET - /recurring/{your_customer_reference}

JSON Response

{
    "success": true,
    "data": {
        "amount": 1000,
        "amount_refunded": 0,
        "costs": [
            {
                "amount": 0.6,
                "description": " Tokenization Generate token transaction ",
                "transaction_id": 767288,
                "type": "SYSTEM"
            }
        ],
        "created": "2019-10-24T13:22:45",
        "currency": "EUR",
        "custom_info": {
            "custom_1": null,
            "custom_2": null,
            "custom_3": null
        },
        "customer": {
            "address1": null,
            "address2": null,
            "city": null,
            "country": null,
            "country_name": null,
            "email": "",
            "first_name": null,
            "house_number": null,
            "last_name": null,
            "locale": "nl_NL",
            "phone1": null,
            "phone2": "",
            "reference": "AutoQAReference",
            "state": null,
            "zip_code": null
        },
        "description": "Tokenization - ALL - Trx with previous token with unscheduled model when is disabled",
        "fastcheckout": "NO",
        "financial_status": "completed",
        "items": null,
        "modified": "2019-10-24T13:22:45",
        "order_id": "my-order-id",
        "payment_details": {
            "account_holder_name": "Testperson-nl",
            "account_id": null,
            "card_expiry_date": 1112,
            "external_transaction_id": 929711011483,
            "last4": 1111,
            "recurring_id": "azbkvsE0up4",
            "recurring_model": "unscheduled",
            "type": "VISA"
        },
        "payment_methods": [
            {
                "account_holder_name": "Testperson-nl",
                "amount": 1000,
                "card_expiry_date": 1112,
                "currency": "EUR",
                "description": "Tokenization - ALL - Trx with previous token with unscheduled model when is disabled",
                "external_transaction_id": 929711011483,
                "last4": 0,
                "payment_description": "Visa CreditCards",
                "status": "completed",
                "type": "VISA"
            }
        ],
        "reason": "Successful approval/completion",
        "reason_code": "",
        "related_transactions": null,
        "status": "completed",
        "transaction_id": 2728879,
        "payment_url": " https://payv2.multisafepay.com/connect/99wi0OTuiCaTY2nwEiEOybWpVx8MNwrJ75c/?lang=nl_NL ",
        "cancel_url": " http://www.example.com/client/notification?type=cancel "
    }
}

List all tokens for a customer reference

This API call allows you to list all tokens related to a single customer reference.

All parameters shown are required field(s)

Parameter	Type	Description
token	string	The unique token linked to the customer reference.

Read our decicated documentation on Tokenization

GET - recurring/{your_customer_reference}/token/{your_token}

JSON Response

{
    "success": true,
    "data": {
        "token": "azbkvsE0up4",
        "code": "MASTERCARD",
        "display": "Card xxxx xxxx xxxx 4444",
        "bin": 555555,
        "name_holder": "Testperson-nl",
        "expiry_date": 3611,
        "expired": 0,
        "last4": 4444,
        "model": "cardOnFile"
    }
}

Get info of a token

This API call allows you to retreive the information related to a single token.

All parameters shown are required field(s)

Parameter	Type	Description
token	string	The unique token linked to the customer reference.

Read our decicated documentation on Tokenization

DELETE - recurring/{your_customer_reference}/remove/{your_token}

JSON Response
{
    "success": true,
    "data": {
        "removed": true
    }
}

Delete a token

This API call allows you to delete a token related to a single customer reference.

All parameters shown are required field(s)

Parameter	Type	Description
token	string	The unique token linked to the customer reference.

"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",

"notification_method": "POST",

"close_window": "true",

payment_option, object

Parameter	Type	Description
notification_url	string	Endpoint where we will send the notifications to notification_url

Parameter	Type	Description
redirect_url	string	Customer will be redirected to this page after a successful payment. In the event that the transaction is marked with the status uncleared, the customer will also be redirected to this page of the webshop. The uncleared status will not be passed on to the customer who will experience the payment as successful at all times.

Parameter	Type	Description
cancel_url	string	Customer will be redirected to this page after a failed payment.

Parameter	Type	Description
notification_method	string	Enables push notifications (POST,GET) default: GET.

Parameter	Type	Description
close_window	bool	true, false.

Plugin information

This plugin information is required for a Community Integration. For more information about these requirments, please read more about a community integration on our documentation page.

Parameter	Type	Description
shop	string	The ecommerce platform in use.
plugin_version	string	The version of the plugin.
shop_version	string	The version of the ecommerce webshop.
partner	string	The third party developing the ecommerce webshop.
shop_root_url	string	The primary URL of the ecommerce webshop.

Plugin and/or integration related information

"plugin": {
    "shop": "ApiTestTool",
    "plugin_version": "1.0.0",
    "shop_version": "1",
    "partner": "partner",
    "shop_root_url": "http://multisafepay.com"
}

Transaction Statuses

Transactions can have the following statuses:

Read more about the difference between the Status and the Financial Status on our Documentation Center.

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

    
    "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": ""
                }
            }
        }
    },

Dynamic Styling

This template can be added to your transaction request for dynamic styling of your payment page.

Below you can find an explanation of the settings which can be included in the transaction request:

Setting	Description
hide_logo	Hides header logo
iframe_mode	Hides various sections e.g. logo, header
hide_flags	Hides flags container
hide_powered	Hides powered link
hide_cart	Hides cart container
hide_btn_cancel	Hides button cancel
hide_cc_logos	Hides creditcard logos
hide_btn_all_methods	Hides all methods button

Read more about dynamic styling for a payment page.

POST - /partners

{
    "product": "connect300",
    "company_name": "Company name Partner",
    "address1": "Kraanspoor",
    "address2": "",
    "house_number": "39C"
    "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": ""
    }
}

Create a merchant account

Please note: This API call currently only works in a ‘Live’ environment. The functioning of this API call in the ‘Test’ environment will follow.

If you have any questions, please contact [email protected]

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

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

Create a website profile in MultiSafepay Control

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

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" 
}

Server to Server API Calls

3D Enabled Request

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	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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. In the event that the transaction is marked with the status uncleared, the customer will also be redirected to this page of the webshop. The uncleared status will not be passed on to the customer who will experience the payment as successful at all times.
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 (Card Verification Code) number is a 3 or 4 digit code used as an additional security feature for card not present transactions. For some cards like MAESTRO, this may not be required. CVC is also not required for recurring transactions.

Read more about Server to Server on our documentation page.

POST - /orders

{
    "type": "direct",
    "order_id": "my-order-id-1",
    "currency": "EUR",
    "amount": 1000,
    "gateway": "CREDITCARD",
    "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": "89.20.162.110",
        "forwarded_ip": "",
        "first_name": "Testperson-nl",
        "last_name": "Approved",
        "address1": "Kraanspoor",
        "address2": "",
        "house_number": "39C",
        "zip_code": "1033 SC",
        "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": {
        "card_number": "5555555555554444",
        "card_holder_name": "MasterCard-Test-Order",
        "card_expiry_date": "2512",
        "card_cvc": "123"
    }
}

JSON Response

{
  "success": true,
  "data": {
    "amount": 1000,
    "amount_refunded": 0,
    "costs": [
      {
        "amount": ,
        "description": "",
        "transaction_id": 2056142,
        "type": "SYSTEM"
      }
    ],
    "created": "2020-01-28T09:01:07",
    "currency": "EUR",
    "custom_info": {
      "custom_1": null,
      "custom_2": null,
      "custom_3": null
    },
    "customer": {
      "address1": "Kraanspoor",
      "city": "Amsterdam",
      "country": "NL",
      "country_name": Netherlands,
      "email": "[email protected]",
      "first_name": "Testperson-nl",
      "house_number": "39C",
      "locale": "nl_NL",
      "phone1": "0208500500",
      "zip_code": "1033 SC"
    },
    "description": "product description",
    "fastcheckout": "NO",
    "financial_status": "initialized",
    "items": null,
    "modified": "2020-01-28T09:01:07",
    "order_id": "my-order-id-1",
    "payment_details": {
      "account_holder_name": "MasterCard-Test-Order",
      "account_id": null,
      "card_expiry_date": 2512,
      "external_transaction_id": "6652390295520298",
      "last4": 4444,
      "recurring_id": null,
      "recurring_model": null,
      "type": "MASTERCARD"
    },
    "payment_methods": [
      {
        "account_holder_name": "Testperson-nl",
        "amount": 1000,
        "card_expiry_date": 2512,
        "currency": "EUR",
        "description": "Product Description",
        "external_transaction_id": "6652390295520298",
        "last4": 4444,
        "payment_description": "MasterCard",
        "status": "initialized",
        "type": "MASTERCARD"
      }
    ],
    "reason": "3D Secure Authorization",
    "reason_code": "",
    "related_transactions": null,
    "status": "initialized",
    "transaction_id": 4034377,
    "customer_verification": {
      "type": "form",
      "html": "",
    },
    "payment_url": "https://payv2.multisafepay.com/connect/99wi0OTuiCaTY2nwEiEOybWpVx8MNwrJ75c/?lang=nl_NL",
    "cancel_url": "http://www.example.com/client/notification?type=cancel"
  }
}

Credit Cards Server to Server

This is a standard credit card API direct order request The gateway has been set to CREDITCARD. In this case, the type of credit card will be detected based on the first four digits.

Please note: Server to Server must first be enabled by our Risk department. Read more about activation on our documentation page.

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	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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. In the event that the transaction is marked with the status uncleared, the customer will also be redirected to this page of the webshop. The uncleared status will not be passed on to the customer who will experience the payment as successful at all times.
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 (Card Verification Code) number is a 3 or 4 digit code used as an additional security feature for card not present transactions. For some cards like MAESTRO, this may not be required. CVC is also not required for recurring transactions.

Read more about Server to Server on our documentation page.

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": {
        ...
    }
}

3D disabled or NON 3D transaction

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	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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. In the event that the transaction is marked with the status uncleared, the customer will also be redirected to this page of the webshop. The uncleared status will not be passed on to the customer who will experience the payment as successful at all times.
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 (Card Verification Code) number is a 3 or 4 digit code used as an additional security feature for card not present transactions. For some cards like MAESTRO, this may not be required. CVC is also not required for recurring transactions.

Read more about Server to Server on our documentation page.

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"
    }
}

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.

The parameter flexible_3d is a property of gateway_info in the POST request.

Activating Flexible 3D secure will override the rules of the Dynamic 3D settings, meaning that payments will not be enrolled with a 3D authentication.

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	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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.

POST - /orders

{
    "type": "direct",
    "order_id": "my-order-id-1",
    "currency": "EUR",
    "amount": 10,
    "gateway": "CREDITCARD",
    "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": true
    },
    "customer": {
        "locale": "nl_NL",
        "ip_address": "89.20.162.110",
        "forwarded_ip": "",
        "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": true,
        "card_number": "",
        "card_holder_name": "",
        "card_expiry_date": "",
        "card_cvc": ""
    }
}

JSON Response

{
  "success": true,
  "data": {
    "amount": 10,
    "amount_refunded": 0,
    "costs": [],
    "created": "2020-02-24T15:11:23",
    "currency": "EUR",
    "custom_info": {
      "custom_1": null,
      "custom_2": null,
      "custom_3": null
    },
    "customer": {
      "address1": "Kraanspoor",
      "city": "Amsterdam",
      "country": "NL",
      "country_name": Netherlands,
      "email": "[email protected]",
      "first_name": "Testperson-nl",
      "house_number": "39C",
      "last_name": "Approved",
      "locale": "nl_NL",
      "phone1": "0208500500",
      "zip_code": "1033 SC"
    },
    "description": "Test Product Description",
    "fastcheckout": "NO",
    "financial_status": "initialized",
    "items": null,
    "modified": "2020-02-24T15:11:23",
    "order_id": "my-order-id-1",
    "payment_details": {
      "account_holder_name": "",
      "account_id": null,
      "card_expiry_date": ,
      "external_transaction_id": null,
      "last4": ,
      "recurring_id": null,
      "recurring_model": null,
      "type": "MASTERCARD"
    },
    "payment_methods": [
      {
        "account_holder_name": "",
        "amount": 10,
        "card_expiry_date": ,
        "currency": "EUR",
        "description": "Test Product Description",
        "payment_description": "MasterCard",
        "status": "initialized",
        "type": "MASTERCARD"
      }
    ],
    "reason": "3DS Enrolled",
    "reason_code": "",
    "related_transactions": null,
    "status": "initialized",
    "transaction_id": 335244060,
    "var1": null,
    "var2": null,
    "var3": null,
    "customer_verification": {
      "html": "<html>\n <head>\n <title>PaReq Form Submission</title>\n <script type=\"text/javascript\">\n function onLoadHandler(){ document.getElementById('PaReqForm').submit(); }\n </script>\n </head>\n <body onLoad=\"onLoadHandler();\">\n <form id=\"PaReqForm\" action=\"https://www.securesuite.co.uk/ing_retail/tdsecure/opt_in_dispatcher.jsp?VAA=B\" method=\"post\">\n <noscript>\n <center><br/>\n <h1>Processing your Transaction</h1>\n <h2>JavaScript is currently disabled or not supported by your browser.</h2><br/>\n <h3>Please click Proceed to continue the processing of your transaction.</h3>\n <input type=\"submit\" value=\"Proceed\"/>\n </center>\n </noscript>\n <input type=\"hidden\" name=\"PaReq\" value=\"eJxVkslu2zAQhl/FyL3iKss0JgTSOkhzUBEkvrg3mhrbCqwlFNXaefoOvdQtIAjzDZf5/xnCchcQ\r\nF2/ox4AWShwGt8VJXd3feZ1XxUZzqaZGy02+LtTaOOlm1bQQSvE7Cy8Pr/hh4ReGoe5aKzKeSWBX\r\npNuC37k2WnD+4+vzDyunRmracUFoMDwvrOA8fcDOCK1r0C4f35aT9AN2YvDd2MZwtLmcAbsCjGFv\r\ndzH2c8aacR/rwW2wd8cvFTZd5ruG9ftxW7fb0I09izhEillDFtvYMZEVZ8XpFmA3uS9jigaqeqgr\r\nu3r3n6v3/a5sHvXPxUqVy/KzfMrF+un3PbC0AyoX0UouOZdST4SeCzGXCtgpD65JcsknOT+H0KcK\r\nD7f8vww0i4CtP1pTJK9XAjz0XUvKLUn+G0OFg7d96KrRx0mCUPeR+k/V0wqwm5tv39MofKQua14I\r\nYZSQxmjNc5OGclpIVWpqrVSckhcAlo6yy7ypU6dnQtF/z+cPnVPCWQ==\"/>\n <input type=\"hidden\" name=\"TermUrl\" value=\"https://pay.multisafepay.com/direct/complete/?mspid=335263060\"/>\n <input type=\"hidden\" name=\"MD\" value=\"b73b9a2a8d671330null,c45d7f40236942f5b73b9a2a8d671330\"/>\n </form>\n </body>\n</html>\n",
      "type": "form"
    },
    "payment_url": "https://payv2.multisafepay.com/connect/99wi0OTuiCaTY2nwEiEOybWpVx8MNwrJ75c/?lang=nl_NL",
    "cancel_url": "http://www.example.com/client/notification?type=cancel&transactionid=apitool_"
  }
}

Direct Server to Server, Flexible 3D set on true

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, while activating Flexible 3D secure will override the rules of the Dynamic 3D settings, meaning that payments will not be enrolled with a 3D authentication.

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	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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.

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"
    }
}

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.

Activating Flexible 3D secure will override the rules of the Dynamic 3D settings, meaning that payments will not be enrolled with a 3D authentication.

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	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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.
email	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.

POST - /orders

{
    "type": "redirect",
    "order_id": "order_id_0000001",
    "gateway": "",
    "currency": "EUR",
    "amount": "10000",
    "description": "Manual Capture Test",
    "manual": "false",
    "capture": "manual",
    "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",
        "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"
    }
}

JSON Response

{
    "success": true,
    "data": {
        "order_id": "order_id_0000001",
        "payment_url": "https://payv2.multisafepay.com/connect/13oElUaESR7YS2b4gUJV9oI4tUXeb1mj1D8/?lang=nl_NL"
    }
}

Manual Capture Authorization

Manual Capture is a feature that allows payments to be captured once an order has been shipped or received. The API calls mandate whether a transaction should be captured partially or fully, as well as the authorization and cancellation of the transaction.

The feature can only be used with specific credit card payment methods including MasterCard, VISA and Maestro.

Parameter	Type	Description
type	string	Specifies the payment flow for the checkout process. Options: redirect, direct, checkout, paymentlink.
order_id	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string. Required. Max 50 char.
gateway	string	The unique gateway id to immediately direct the customer to the payment method. You retrieve these gateways using a gateway request.
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.
capture	string	A manual capture has been generated.
payment_options	object
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.
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

Read more about Manual Capture on our documentation page.

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"
    }
}

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.

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	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string.
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. In the event that the transaction is marked with the status uncleared, the customer will also be redirected to this page of the webshop. The uncleared status will not be passed on to the customer who will experience the payment as successful at all times.
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.
email	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.

POST - /orders//capture

{
 "amount": "2000",
 "new_order_id": "my-order-id-01",
 "new_order_status": "completed",
 "invoice_id": "",
 "carrier": "",
 "reason": "",
 "memo": "",
 "checkout_data": {}
}

JSON Response

{
    "success": true,
    "data": {
        "transaction_id": 001,
        "order_id": "my-order-id-01"
    }
}

Partial Capture

Parameter	Type	Description
amount	integer	The amount (in cents) that the customer needs to pay.
new_order_id	integer / string	The unique identifier from your system for the order (max. 50 chars).
new_order_status	string	The current status of the order.
invoice_id	integer / 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 (max. 50 chars).
carrier	string	The name of the shipping company delivering the customer’s order.
reason	string	Add a short text memo based on the capture reason of the order.
memo	string	Add a short action text memo mentioning the shipping status of the order.
checkout_data	object	Contains the original shopping cart + copied items to be refunded.
order_id	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string (max. 50 chars).

Read more about Manual Capture on our documentation page.

POST - /orders//capture

{
 "amount": "10000",
 "new_order_id": "my-order-id-01",
 "new_order_status": "completed",
 "invoice_id": "001",
 "carrier": "",
 "reason": "",
 "memo": "",
 "checkout_data": {}
}

JSON Response

{
    "success": true,
    "data": {
        "transaction_id": 001,
        "order_id": "my-order-id-01"
    }
}

Full Capture

Parameter	Type	Description
amount	integer	The amount (in cents) that the customer needs to pay.
new_order_id	integer / string	The unique identifier from your system for the order (max. 50 chars).
new_order_status	string	The current status of the order.
invoice_id	integer / 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 (max. 50 chars).
carrier	string	The name of the shipping company delivering the customer’s order.
reason	string	Add a short text memo based on the capture reason of the order.
memo	string	Add a short action text memo mentioning the shipping status of the order.
checkout_data	object	Contains the original shopping cart + copied items to be refunded.
order_id	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string (max. 50 chars).

Read more about Manual Capture on our documentation page.

GET - /orders/

JSON Response

{
    "success": true,
    "data": {
        "transaction_id": 001,
        "order_id": "my-order-id-1",
        "created": "2019-03-22T12:03:56",
        "currency": "EUR",
        "amount": 1000,
        "description": "Manual Capture Test",
        "var1": null,
        "var2": null,
        "var3": null,
        "items": null,
        "amount_refunded": 0,
        "status": "completed",
        "financial_status": "completed",
        "reason": "",
        "reason_code": "",
        "fastcheckout": "NO",
        "modified": "2019-03-22T12:03:58",
        "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]"
        },
        "payment_details": {
            "recurring_id": null,
            "type": "VISA",
            "account_id": null,
            "account_holder_name": "MultiSafepay",
            "external_transaction_id": null,
            "last4": 1111,
            "card_expiry_date": 4412
        },
        "costs": [
            {
                "transaction_id": 001,
                "description": "",
                "type": "SYSTEM",
                "amount":
            }
        ],
        "related_transactions": null,
        "payment_methods": [
            {
                "account_holder_name": "MultiSafepay",
                "amount": 1000,
                "card_expiry_date": 4412,
                "currency": "EUR",
                "description": "Manual Capture Test",
                "last4": 1111,
                "payment_description": "Visa CreditCards",
                "status": "completed",
                "type": "VISA"
            }
        ]
    }
}

Order Status Captured Transaction

Parameter	Type	Description
order_id	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string (max. 50 chars)

Read more about Manual Capture on our documentation page.

GET - /orders/

JSON Response

{
    "success": true,
    "data": {
        "transaction_id": 001,
        "order_id": "my-order-id-1",
        "created": "2019-03-22T10:32:52",
        "currency": "EUR",
        "amount": 9743,
        "description": "",
        "var1": null,
        "var2": null,
        "var3": null,
        "items": null,
        "amount_refunded": 0,
        "status": "completed",
        "financial_status": "initialized",
        "reason": "",
        "reason_code": "",
        "fastcheckout": "NO",
        "modified": "2019-03-22T10:32:52",
        "customer": {
            "locale": "nl_NL",
            "first_name": "Testperson-nl",
            "last_name": "Approved",
            "address1": "Kraanspoor",
            "address2": null,
            "house_number": "39C",
            "zip_code": "1033 SC",
            "city": "Amsterdam",
            "state": null,
            "country": "NL",
            "country_name": null,
            "phone1": "0208500500",
            "phone2": "",
            "email": "[email protected]"
        },
        "payment_details": {
            "recurring_id": 57876598769,
            "type": "VISA",
            "account_id": null,
            "account_holder_name": "MultiSafepay",
            "external_transaction_id": 234374824,
            "last4": 1111,
            "card_expiry_date": 4412,
            "capture": "manual",
            "capture_expiry": "2020-06-06T05:53:44",
            "capture_remain": 9743
        },
        "costs": [
            {
                "transaction_id": 001,
                "description": "",
                "type": "SYSTEM",
                "amount": 2.83
            }
        ],
        "related_transactions": null,
        "payment_methods": [
            {
                "account_holder_name": "MultiSafepay",
                "amount": 9743,
                "card_expiry_date": 4412,
                "currency": "EUR",
                "description": "MultiSafepay Test",
                "external_transaction_id": 234374824,
                "last4": 1111,
                "payment_description": "Visa CreditCards",
                "status": "initialized",
                "type": "VISA"
            }
        ]
    }
}

Order Status Authorized Transaction

Parameter	Type	Description
order_id	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string. Required. Max 50 char.

Read more about Manual Capture on our documentation page.

PATCH - /capture/

{
 "status": "cancelled",
 "reason": "cancel reservation note text"
}

JSON Response

{
    "success": true,
    "data": {
        ...
    }
}

Cancel Authorization / Reservation

Parameter	Type	Description
reason	string	Add a short text memo based on the capture reason of the order.
status	string	The order status of the manual capture request.

Read more about Manual Capture on our documentation page.

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"
  }
}

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.

Parameter	Type	Description
type	string	Specifies the payment flow for the checkout process. Fill in ‘paymentlink’.
order_id	integer / string	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string. 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.

POST - /orders

{
    "type": "redirect",
    "order_id": "my-order-id-1",
    "gateway": "",
    "currency": "EUR",
    "amount": "0",
    "description": "Zero Authorization Test",
    "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": "80.123.456.78",
        "forwarded_ip": "",
        "first_name": "Testperson-nl",
        "last_name": "Approved",
        "address1": "Kraanspoor",
        "address2": "",
        "house_number": "39C",
        "zip_code": "1033 SC",
        "city": "Amsterdam",
        "state": "",
        "country": "NL",
        "birthday": "01011993",
        "gender": "male",
        "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"
    }
}

JSON Response

{
  "success": true,
  "data": {
    "order_id": "My-order-id-1",
    "payment_url": "https://payv2.multisafepay.com/connect/99wi0OTuiCaTY2nwEiEOybWpVx8MNwrJ75c/?lang=nl_NL"
  }
}

Zero Authorization

For a number of scenarios, it can be useful for our merchants to verify an account with Zero Authorization. An amount of zero will be reserved to check the authenticity of the card as well as establish an authorization to collect future payments.

The amount parameter should be set to 0.

Parameter	Type	Description
type	string	Specifies the payment flow for the checkout process. Options: redirect, direct, checkout, paymentlink.
order_id	string \| integer	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string. Required. (max. 50 chars).
gateway	string	The unique gateway id to immediately direct the customer to the payment method. You retrieve these gateways using a gateway request.
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
customer	object

Read more about Zero Authorization on our documentation page.

GET - /orders/

JSON Response

{
  "success": true,
  "data": {
    "amount": 0,
    "amount_refunded": 0,
    "costs": [],
    "created": "2019-10-17T10:44:59",
    "currency": "EUR",
    "custom_info": {
      "custom_1": null,
      "custom_2": null,
      "custom_3": null
    },
    "customer": {
      "address1": "Kraanspoor",
      "address2": null,
      "city": "Amsterdam",
      "country": "NL",
      "country_name": null,
      "email": "[email protected]",
      "first_name": "Testperson-nl",
      "house_number": "39C",
      "last_name": null,
      "locale": "nl_NL",
      "phone1": "0208500500",
      "phone2": "",
      "state": null,
      "zip_code": "1033 SC"
    },
    "description": "MultiSafepay Test",
    "fastcheckout": "NO",
    "financial_status": "completed",
    "items": null,
    "modified": "2019-09-17T10:44:59",
    "order_id": "my-order-id-1",
    "payment_details": {
      "account_holder_name": "MultiSafepay",
      "account_id": null,
      "card_expiry_date": 4412,
      "external_transaction_id": 234374824,
      "last4": 1111,
      "recurring_id": "57876598769",
      "recurring_model": null,
      "type": "VISA"
    },
    "payment_methods": [
      {
        "account_holder_name": "MultiSafepay",
        "amount": 9743,
        "card_expiry_date": 2203,
        "currency": "EUR",
        "description": "MultiSafepay Test",
        "external_transaction_id": 234374824,
        "last4": 0,
        "payment_description": "Visa CreditCards",
        "status": "completed",
        "type": "VISA"
      }
    ],
    "reason": "Successful approval/completion",
    "reason_code": "",
    "related_transactions": null,
    "status": "completed",
    "transaction_id": 001,
    "var1": null,
    "var2": null,
    "var3": null
  }
}

Order Status

Parameter	Type	Description
order_id	string \| integer	The unique identifier from your system for the order. If the values are only numbers the type will be integer, otherwise it will be string. Required. (max. 50 chars).

Read more about Zero Authorization on our documentation page.

API

How to navigate the API documentation

What our API offers:

Postman

Overview

Environments

Authentication

Localization

Discount

Discount added as order rule (which is non-refundable)

Discount added as unit price

Gateways

Retrieve a gateway

Retrieve gateways - Multiple available giftcards

Gateway Issuers

Orders

Create a Redirect order

Create a Direct Order

Recurring Payment

Split Payments

Update an order

Retrieve an order

Dynamic Template

Payment methods

AfterPay

Direct - AfterPay

Redirect - AfterPay

Alipay

Redirect

Direct

American Express

Apple Pay

Apple Pay Direct

Bancontact

Bancontact QR

Bank transfer

Redirect - Bank transfer

Direct - Bank transfer

Belfius

Redirect

Direct

Co-branded credit card

Credit Cards

Dotpay

E-invoicing

Direct - E-invoicing

Redirect - E-invoicing

EPS

Giropay

Gift card

iDEAL QR

iDEAL

Redirect - iDEAL

Direct - iDEAL

ING Home’Pay

Direct

Redirect

Klarna

Direct - Klarna

Redirect - Klarna (Klarna Payments)

KBC

Redirect

Direct

Pay After Delivery

Redirect - Pay After Delivery

Direct - Pay After Delivery

PayPal

Redirect

Direct

Santander Betaalplan

SOFORT

Redirect

Direct

Trustly

TrustPay

SEPA Direct Debit

Redirect

Direct

Maestro

Mastercard