1. Home
  2. API

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 requests that allows you to retrieve order information, post payments in our API documentation.

Overview

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 Environment

LIVE Environment

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

Example with discount in separate order rule:

{
	"type": "redirect",
	"gateway": "PAYAFTER",
	"order_id": "my-order-id-1",
	"currency": "EUR",
	"amount": 17424,
	...
	"shopping_cart": {
		"items": [{
			"name": "Geometric Candle Holders",
			"description": "",
			"unit_price": 90.00,
			"quantity": 2,
			"merchant_item_id": "111111",
			"tax_table_selector": "none",
			"weight": {
				"unit": "KG",
				"value": 12
			}
		}, {
			"name": "20% discount on all items",
			"description": "Discount",
			"unit_price": -43.56,
			"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",
					"rules": [{
						"rate": 0.21
					}]
				},
				{
					"name": "none",
					"rules": [{
						"rate": 0.00
					}]
				}
			]
		}
	}
}

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

Adding a discount as an order rule is a common way to add a discount before submitting a transaction request at MultiSafepay. However, adding a discount as an order rule may result in a conflict when partially refunding a post-paid payment method transaction. This is most common when the discount is a percentage. Adding a discount as a seperate discount rule, will conflict when partially refunding a post-paid 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.

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": "my-order-id-1",
    "currency": "EUR",
    "amount": 20800,
    ...
    "shopping_cart": {
        "items": [
            {
                "name": "Geometric Candle Holders",
                "description": "",
                "unit_price": 72,
                "quantity": 2,
                "merchant_item_id": "111111",
                "tax_table_selector": "BTW21",
                "weight": {
                    "unit": "KG",
                    "value": 12
                }
            },
            {
                "name": "20% discount on all items",
                "description": "Discount",
                "unit_price": 13930,
                "quantity": 1,
                "merchant_item_id": "discount",
                "tax_table_selector": "none"
            }
        ]
    },
    "checkout_options": {
        "tax_tables": {
            "default": {
                "shipping_taxed": "true",
                "rate": 0.21
            },
            "alternate": [
                {
                    "name": "BTW21",
                    "rules": [
                        {
                            "rate": 0.21
                        }
                    ]
                },
                {
                    "name": "none",
                    "rules": [
                        {
                            "rate": 0.00
                        }
                    ]
                }
            ]
        }
    }
}

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

id | string

The unique identifier of the gateway to be returned.

GET - /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 gift cards

Parameter

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 gift cards in the response. See the response example on the side.

If the parameter include=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": "1235",
      "description": "Handelsbanken"
    }
  ]
}

Gateway Issuers

Parameter

id | string

The unique identifier of the payment gateway to retrieve an issuer list for. 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
0021 Rabobank
0771 Regio Bank
Soon supported Revolut
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.

Parameters

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

Customer will be redirected to this page after a failed payment.

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

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-1",
    "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-1",
    "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, CREDITCARD, PAYAFTER, EINVOICE, KLARNA, DIRDEB, DIRECTBANK, BANKTRANS, PAYPAL, BELFIUS, ING, KBC, CBC, ALIPAY

Parameters

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 description will also be shown on the customer’s bank statement. Max. 200 characters. HTML is not 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 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.

POST - /json/padprechecks

{
    "type": "checkout",
    "gateway" : "PAYAFTER",
    "order_id": "my-order-id-1",
    "currency": "EUR",
    "amount": "9000",
    "description": "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"
    },
    "customer": {
        "locale": "nl_NL",
        "ip_address": "184.43.169.4",
        "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/testtool/client/json-test",
        "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": "0612345678",
        "email": "[email protected]"
    },
    "shopping_cart": {
        "items": [
            {
                "name": "Geometric Candle Holders",
                "description": "",
                "unit_price": "90",
                "quantity": "1",
                "merchant_item_id": "hdd006",
                "tax_table_selector": "BTW0",
                "weight": {
                    "unit": "KG",
                    "value": "1"
                }
            }
        ]
    },
    "checkout_options": {
        "rounding_policy": {
            "mode": "UP",
            "rule": "PER_ITEM"
        },
        "shipping_methods": {
            "flat_rate_shipping": [
                {
                    "name": "TNT - verzending NL",
                    "price": "7",
                    "allowed_areas": [
                        "NL",
                        "ES"
                    ]
                },
                {
                    "name": "Seur - Spain",
                    "price": "7",
                    "allowed_areas": [
                        "NL",
                        "ES"
                    ]
                },
                {
                    "name": "TNT - verzending BE en FR",
                    "price": "12",
                    "excluded_areas": [
                        "NL",
                        "FR",
                        "ES"
                    ]
                }
            ]
        },
        "tax_tables": {
            "alternate": [
                {
                    "name": "BTW0",
                    "rules": [
                        {
                            "rate": "0.00"
                        }
                    ]
                },
                {
                    "name": "2",
                    "rules": [
                        {
                            "rate": "0.09",
                            "country": "US"
                        }
                    ]
                }
            ]
        }
    },
    "custom_fields": [
        {
            "name": "acceptagreements",
            "type": "checkbox",
            "label": "This label",
            "description_right": {
                "value": [
                    {
                        "nl": "Ik ga akkoord met de <a href='http://test.nl' target='_blank'>algemene voorwaarden</a>"
                    },
                    {
                        "en": "I accept the <a href='http://test.nl' target='_blank'>terms and conditions</a>"
                    }
                ]
            },
            "validation": {
                "type": "regex",
                "data": "^[1]$",
                "error": [
                    {
                        "nl": "U dient akkoord te gaan met de algemene voorwaarden"
                    },
                    {
                        "en": "Please accept the terms and conditions"
                    }
                ]
            }
        },
        {
            "standard_type": "companyname"
        }
    ]
}

JSON Response

{
  "success": true,
  "data": {
    "result": false | true
  }
}

Pay After Delivery Pre-check

A Pay After Delivery order can have a pre-check carried out. This type of request contains all data related to the order and customer.

The pre-check decides if MultiSafepay accepts the order or whether the customer is required to selected a different payment methods to complete the transaction.

Parameters

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 description will also be shown on the customer’s bank statement. Max. 200 characters. HTML is not 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

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

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. If you are using your own integration, the transaction should be sent including the complete specification of the shopping_cart.

items | object

Specification of products (items) which can be set in order to be displayed on the checkout page. The descriptions of these parameters can be viewed in the shopping_cart.items API section.

POST - /orders

{
    "type": "direct",
    "order_id": "my-order-id-1",
    "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-1",
    "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_US",
      "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, Bancontact and SOFORT Banking can be used for an initial payment as well, and followed up by a recurring payment with SEPA Direct Debit. A standard transaction must first be created with recurring payments enabled. The recurring ID can then be requested by retreiving an order and payments can be initiated repeatedly by using recurring payments

For more information please visit our documentation page to read more about recurring payments

Parameters

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 description will also be shown on the customer’s bank statement. Max. 200 characters. HTML is not 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 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.

POST - /orders

{
    "type": "redirect",
    "order_id": "my-order-id-1",
    "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-1",
    "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.

Parameters

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 description will also be shown on the customer’s bank statement. Max. 200 characters. HTML is not 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 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.

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}

{
    "id": "MSP12345",
    "status": "shipped",
    "tracktrace_code": "3SMSP0123456789",
    "tracktrace_url": "http://tracktrace-url.com/",
    "carrier": "MSP Logistics",
    "ship_date": "01-01-1911",
    "reason": "Fulfilled by warehouse",
    "invoice_id": "AB12345",
    "invoice_url": "http://mspinvoice-AB12345.com"
    "po_number": ""
}

JSON Response

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

Update an order

Update the order details.

Parameters

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.

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.

invoice_url | string

The invoice url linking to the invoice_id.

po_number | string

The Purchase Order number of the shipping company.

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": "0208500500",
      "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.

Parameters

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

Parameters

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.

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

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": "26000",
    "description": "Test Order Description",
    "manual": "false",
    "gateway_info": {
        "birthday": "1970-07-10",
        "gender": "mr",
        "phone": "0612345678",
        "email": "[email protected]"
    },
    "payment_options": {
        "notification_url": "http://www.example.com/client/notification?type=notification",
        "redirect_url": "http://www.example.com/client/notification?type=redirect",
        "cancel_url": "http://www.example.com/client/notification?type=cancel", 
        "close_window": ""
    },
    ...
    "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"
                }
            },
        ]
    },
    "checkout_options": {
        "tax_tables": {
            "alternate": [
                {
                    "name": "none",
                    "rules": [
                        {
                            "rate": "0.00"
                        }
                    ]
                }
            ]
        }
    }
}

JSON Response

{
  "success": true,
  "data": {
    "amount": 26000,
    "amount_refunded": 0,
    "checkout_options": {
      "alternate": [
        {
          "name": "none",
          "rules": [
            {
              "country": "",
              "rate": "0.00"
            }
          ]
        }
      ],
      "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": {
    },
    ...
    
    "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"
  }
}

POST - /orders

{
    "type": "redirect",
    "gateway": "AFTERPAY",
    "order_id": "my-order-id-1",
    "currency": "EUR",
    "amount": "26000",
    "description": "Test Order Description",
    "items": "",
    "manual": "false"
    ...
    "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 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": {
            "alternate": [
                {
                    "name": "none",
                    "rules": [
                        {
                            "rate": "0.00"
                        }
                    ]
                }
            ]
        }
    }
}

JSON Response

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

AfterPay

Direct - AfterPay

Creates an AfterPay Direct order to be paid after delivery.

  • Direct transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

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: 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 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 not 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 lastname require minimum two characters.

delivery | object

Contains the delivery information for the shipment. _Values for first_name and lastname require minimum two characters.

shopping_cart | object

Contains all purchased items including tax class. If you are using your own integration, the transaction should be sent including the complete specification of the shopping_cart.

Please note: In order for the shopping_cart to function correctly, the shipment item requires a parameter ‘merchant_item_id’ with the value ‘msp-shipping’

items | object

Specification of products (items) which can be set in order to be displayed on the checkout page. Specification of products (items) which can be set in order to be displayed on the checkout page. The descriptions of these parameters can be viewed in the shopping_cart.items API section.

checkout_options | object

Contains the definitions for the VAT class.

gateway_info | object

Contains the issuer_id.

birthday | object

The birth date of the customer in the format yyyy-mm-dd. This is required for credit checks. Required in countries: NL, BE

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 _firstname< and _lastname 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 Redirect order to be paid after delivery.

  • Redirect transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

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: 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 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 not 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 lastname require minimum two characters.

delivery | object

Contains the delivery information for the shipment. _Values for first_name and lastname require minimum two characters.

shopping_cart | object

Contains all purchased items including tax class. If you are using your own integration, the transaction should be sent including the complete specification of the shopping_cart.

Please note: In order for the shopping_cart to function correctly, the shipment item requires a parameter ‘merchant_item_id’ with the value ‘msp-shipping’

items | object

Specification of products (items) which can be set in order to be displayed on the checkout page. Specification of products (items) which can be set in order to be displayed on the checkout page. The descriptions of these parameters can be viewed in the shopping_cart.items API section

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

Please note that _firstname and _lastname 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.

POST - /orders

{
    "type": "direct",
    "gateway": "IN3",
    "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"
    },
    "customer": {
        "ip_address": "89.45.467.110",
        "locale": "nl_NL",
        "first_name": "Testperson-nl",
        "last_name": "",
        "address1": "Kraanspoor",
        "house_number": "39C",
        "zip_code": "1033 SC",
        "city": "Amsterdam",
        "country": "NL",
        "email": "[email protected]"
    },
    "delivery": {
        "first_name": "Testperson-nl",
        "last_name": "",
        "address1": "Kraanspoor",
        "house_number": "39C",
        "zip_code": "1033 SC",
        "city": "Amsterdam",
        "country": "NL",
        "phone": "0208500500",
        "email": "[email protected]"
    },
    "gateway_info": {
        "birthday": "1970-07-10",
        "gender": "mr",
        "phone": "0612345678"
    },
    "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": {
    "amount": 37485,
    "amount_refunded": 0,
    "checkout_options": {
      "alternate": [
        {
          "name": "BTW21",
          "rules": [
            {
              "country": "",
              "rate": "0.21"
            }
          ],
          "standalone": true
        },
        {
          "name": "BTW9",
          "rules": [
            {
              "country": "",
              "rate": "0.09"
            }
          ],
          "standalone": true
        },
        {
          "name": "BTW6",
          "rules": [
            {
              "country": "",
              "rate": "0.06"
            }
          ],
          "standalone": true
        },
        {
          "name": "BTW0",
          "rules": [
            {
              "country": "",
              "rate": "0.00"
            }
          ],
          "standalone": true
        },
        {
          "name": "none",
          "rules": [
            {
              "country": "",
              "rate": "0.00"
            }
          ],
          "standalone": ""
        },
        {
          "name": "FEE",
          "rules": [
            {
              "country": "",
              "rate": "0.00"
            }
          ],
          "standalone": ""
        }
      ],
      "default": {
        "rate": 0.21,
        "shipping_taxed": true
      }
    },
    "costs": [],
    "created": "2020-08-19T14:55:46",
    "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": "",
      "locale": "nl_NL",
      "phone1": "0612345678",
      "zip_code": "1039 SC"
    },
    "description": "Test Order Description",
    "fastcheckout": "NO",
    "financial_status": "initialized",
    "items": "<table border=\"0\" cellpadding=\"5\" width=\"100%\">\n<tr>\n<th width=\"10%\"><font size=\"2\" face=\"Verdana\">Aantal </font></th>\n<th align=\"left\"></th>\n<th align=\"left\"><font size=\"2\" face=\"Verdana\">Details </font></th>\n<th width=\"19%\" align=\"right\"><font size=\"2\" face=\"Verdana\">Prijs </font></th>\n</tr>\n<tr>\n<td align=\"center\"><font size=\"2\" face=\"Verdana\">3</font></td>\n<td width=\"6%\"></td>\n<td width=\"65%\"><font size=\"2\" face=\"Verdana\">Geometric Candle Holders</font></td>\n<td align=\"right\">&euro;<font size=\"2\" face=\"Verdana\">90.00</font>\n</td>\n</tr>\n<tr>\n<td align=\"center\"><font size=\"2\" face=\"Verdana\">1</font></td>\n<td width=\"6%\"></td>\n<td width=\"65%\"><font size=\"2\" face=\"Verdana\">Nice apple</font></td>\n<td align=\"right\">&euro;<font size=\"2\" face=\"Verdana\">35.00</font>\n</td>\n</tr>\n<tr>\n<td align=\"center\"><font size=\"2\" face=\"Verdana\">1</font></td>\n<td width=\"6%\"></td>\n<td width=\"65%\"><font size=\"2\" face=\"Verdana\">Flat Rate - Fixed</font></td>\n<td align=\"right\">&euro;<font size=\"2\" face=\"Verdana\">10.00</font>\n</td>\n</tr>\n<tr bgcolor=\"#E9F1F7\">\n<td colspan=\"3\" align=\"right\"><font size=\"2\" face=\"Verdana\">BTW:</font></td>\n<td align=\"right\">&euro;<font size=\"2\" face=\"Verdana\">59.85</font>\n</td>\n</tr>\n<tr bgcolor=\"#E9F1F7\">\n<td colspan=\"3\" align=\"right\"><font size=\"2\" face=\"Verdana\">Totaal:</font></td>\n<td align=\"right\">&euro;<font size=\"2\" face=\"Verdana\">374.85</font>\n</td>\n</tr>\n</table>",
    "modified": "2020-08-19T14:55:46",
    "order_adjustment": {
      "total_adjustment": 59.85,
      "total_tax": 59.85
    },
    "order_id": "my-order-id-1",
    "order_total": 374.85,
    "payment_details": {
      "account_holder_name": null,
      "account_id": "1970-07-10",
      "external_transaction_id": "34bfc991bef24558a5b4f9c168753da1",
      "recurring_id": null,
      "recurring_model": null,
      "type": "IN3"
    },
    "payment_methods": [
      {
        "account_id": "1970-07-10",
        "amount": 37485,
        "currency": "EUR",
        "description": "Test Order Description",
        "external_transaction_id": "34bfc928374rhjnf9368753da1",
        "payment_description": "in3",
        "status": "initialized",
        "type": "IN3"
      }
    ],
    "reason": "",
    "reason_code": "",
    "related_transactions": null,
    "shopping_cart": {
      "items": [
        {
          "cashback": "",
          "currency": "EUR",
          "description": "",
          "image": "",
          "merchant_item_id": 1111,
          "name": "Geometric Candle Holders",
          "options": [],
          "product_url": "",
          "quantity": 3,
          "tax_table_selector": "BTW21",
          "unit_price": "90.00",
          "weight": {
            "unit": "KG",
            "value": 12
          }
        },
        {
          "cashback": "",
          "currency": "EUR",
          "description": "",
          "image": "",
          "merchant_item_id": 666666,
          "name": "Nice apple",
          "options": [],
          "product_url": "",
          "quantity": 1,
          "tax_table_selector": "BTW9",
          "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": "initialized",
    "transaction_id": 4273483,
    "payment_url": "https://capayable-payment-test.tritac.com/aanbetaling/34bfc991bef24558a5b4f9c168753da1?returnUrl=https%3A%24545F%2Ftestpay.multisafepay.com%2Fdirect%2Fcomplete%2F%3Fmspid%3D4273483&shopOrderExchangeUrl=https%3A%2F%2Ftestpay.multisafepay.com%2Fdirect%2Fcomplete%2F%3Fmspid%3D4273483"
  }
}

POST - /orders

{
    "type": "redirect",
    "gateway": "IN3",
    "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"
    },
    "customer": {
        "ip_address": "45.46.216.114",
        "locale": "nl_NL",
        "first_name": "Testperson-nl",
        "last_name": "",
        "address1": "Kraanspoor",
        "house_number": "39C",
        "zip_code": "1039 SC",
        "city": "Amsterdam",
        "country": "NL",
        "email": "[email protected]"
    },
    "delivery": {
        "first_name": "Testperson-nl",
        "last_name": "",
        "address1": "Kraanspoor",
        "house_number": "39C",
        "zip_code": "1039 SC",
        "city": "Amsterdam",
        "country": "NL",
        "phone": "0612345678",
        "email": "[email protected]"
    },
    "gateway_info": {
        "birthday": "1970-07-10",
        "gender": "mr",
        "phone": "0612345678"
    },
    "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": "apitool_10088776",
    "payment_url": "https://testpayv2.multisafepay.com/connect/82byiUAWKjrn4350x4fhNCzueapaDGvj8cs/?lang=nl_NL"
  }
}

in3

Direct - in3

Creates an in3 Direct order to be paid in installments.

  • Direct transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

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: IN3.

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 not 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 lastname require minimum two characters.

delivery | object

Contains the delivery information for the shipment. _Values for first_name and lastname require minimum two characters.

shopping_cart | object

Contains all purchased items including tax class. If you are using your own integration, the transaction should be sent including the complete specification of the shopping_cart.

items | object

Specification of products (items) which can be set in order to be displayed on the checkout page. The descriptions of the shopping cart parameters can be viewed in the shopping_cart.items API section.

checkout_options | object

Contains the definitions for the VAT class.

gateway_info | object

Contains the issuer_id.

birthday | object

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 _firstname< and _lastname 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 in3 on our documentation page.

Redirect - in3

Creates an in3 Redirect order to be paid in installments.

  • Redirect transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

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: IN3.

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 not 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 lastname require minimum two characters.

delivery | object

Contains the delivery information for the shipment. _Values for first_name and lastname require minimum two characters.

shopping_cart | object

Contains all purchased items including tax class. If you are using your own integration, the transaction should be sent including the complete specification of the shopping_cart.

items | object

Specification of products (items) which can be set in order to be displayed on the checkout page. The descriptions of the shopping cart parameters can be viewed in the shopping_cart.items API section.

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

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",
            "house_number": 39C,
            "city": "Amsterdam",
            "country": "NL",
            "country_name": null,
            "zip_code": "1033SC"
            "email": "[email protected]",
            "locale": "cn_CN",
            "phone1": "0208500500",
        },
        "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 - Alipay

Creates an Alipay Redirect order.

  • Redirect transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

type | string

Specifies the payment flow for the checkout process. Options: redirect, direct, 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.

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.

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 not 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 lastname require minimum two characters.

Read more about Alipay on our documentation page.

Direct - Alipay

Creates an Alipay Direct order.

  • Direct transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

type | string

Specifies the payment flow for the checkout process. Options: redirect, direct, 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.

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.

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 not 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 lastname require minimum two characters.

Note: The ip_address parameter is not required, although its use is recommended to help detect fraudulent payments.

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

Creates an American Express Redirect order.

Besides the individual credit card gateways, MultiSafepay offers you a generic gateway called CREDITCARD. This can save space on your mobile checkout. The disadvantage is that the customer can not immediately see which credit cards can be used. The correct credit card logo will appear automatically when the card holder provides the first digits of the credit card number.

  • Redirect transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

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

Note: The ip_address and e-mail address parameters are not required, although their use is recommended to help detect fraudulent payments.

Read more about American Express on our documentation page.

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

Creates an Apple Pay Redirect order.

  • Redirect transaction requires all fields completed properly.

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

This JavaScript code will detect if Apple Pay is supported on a device. We recommend you to use this code to avoid an error being displayed if the device does not support Apple Pay.

Please note that the code will still display Apple Pay as a payment method on a non-supported device. We recommend extending the script to your own needs in order to hide Apple Pay.

  • All parameters shown are required field(s)

Parameters

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 | 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 not 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": "nl_NL"
    }
}

JSON Response

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

Bancontact

Creates a Bancontact Redirect order.

  • Redirect transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

type | string

Specifies the payment flow for the checkout process. Options: redirect and payment link.

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.

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.

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 not 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": "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_enabled": 1
    },
    "customer": {
        "locale": nl_BE"
    }
}

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

Creates a Bancontact QR Redirect order.

  • Redirect transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

type | string

Specifies the payment flow for the checkout process. Options: redirect and payment link.

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.

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.

currency | string

Has to be EUR.

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

customer | object

After placing the order, you will receive 2 links as response on a successfull Bancontact QR request: a payment link and a qr_url. This qr_url contains a deeplink to Bancontact/MisterCash which can be encoded into a QR image at any later point.

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",
        "country": "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",
        "country": "NL",
        "ip_address": "89.20.162.110",
        "disable_send_email": false,
    }
}

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

Creates a Bank transfer Redirect order.

  • Redirect transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

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 description will also be shown on the customer’s bank statement. Max. 200 characters. HTML is not 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.

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.

country | string

Customer’s provided country code in ISO 3166-1 format e.g. ‘NL’. This will provide a local bank account to the customer to pay to, where available.

Note: The ip_address parameter is not required, although its use is recommended to help detect fraudulent payments.

Read more about bank transfers on our documentation page.

Direct - Bank transfer

Creates a Bank transfer Direct order.

  • Direct transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

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 description will also be shown on the customer’s bank statement. Max. 200 characters. HTML is not 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.

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

disable_send_email (optional) | boolean

Set to True if you will send your own bank transfer payment instructions to customers and do not want MultiSafepay to do this. This value defaults to false.

email | string

The email address where the system can send payment instructions to the customer.

country | string

Customer’s provided country code in ISO 3166-1 format e.g. ‘NL’. This will provide a local bank account to the customer to pay to, where available.

Note: The ip_address parameter is not required, although its use is recommended to help detect fraudulent payments.

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.

Parameters

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",
            "house_number": "39C",
            "zip_code": "1033SC"
            "city": "Amsterdam",
            "country": "NL";,
            "country_name": "Netherlands",
            "phone1": "0208500500",
            "email": "[email protected]",
},
        "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 - Belfius

Creates a Belfius Redirect order.

  • Redirect transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

type | string

Specifies the payment flow for the checkout process. Options: direct , redirect , 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.

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.

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 not supported. Use the ‘items’ or ‘shopping_cart’ objects for this.

payment_options | object

customer | object

Direct - Belfius

Creates a Belfius Direct order.

  • Direct transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

type | string

Specifies the payment flow for the checkout process. Options: direct , redirect , 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.

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.

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 not 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 Belfius on our documentation page.

POST - /orders

{
    "type": "redirect",
    "order_id": "my-order-id-1",
    "gateway": "CBC",
    "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_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",
    "gateway": "CBC",
    "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_BE",
        "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 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",
      "city": "Amsterdam",
      "country": "NL",
      "country_name": null,
      "email": "[email protected]",
      "first_name": "Testperson-nl",
      "house_number": 39C,
      "last_name": "Approved",
      "phone1": "0208500500",
      "locale": "nl_BE",
      "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": "CBC"
    },
    "payment_methods": [
      {
        "amount": 1000,
        "currency": "EUR",
        "description": "Test Order Description",
        "external_transaction_id": 325062361,
        "payment_description": "CBC",
        "status": "initialized",
        "type": "CBC"
      }
    ],
    "reason": "",
    "reason_code": "",
    "related_transactions": null,
    "status": "initialized",
    "transaction_id": 325062361,
    "payment_url": "https://www.cbc.be/olpayment?langWebSite=N&olpId=S132&olpCtx=%2FH8s4RM8GN%2FSKLOcUoTBBPus%2BWBbXCz9ChR12y5ozVDe8Rc70DjFQNQy2TaiSnTOEQkziFEQmgQy%2BHDxrqqzB%2F8I1yk5zE0%"
  }
}

CBC

Redirect - CBC

Creates a CBC Redirect order.

  • Redirect transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

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: CBC.

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 not 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 CBC on our documentation page.

Direct - CBC

Creates a CBC Direct order.

  • Direct transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

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: CBC.

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

Note: The ip_address parameter is not required, although its use is recommended to help detect fraudulent payments.

Read more about CBC 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

Creates a Co-branded credit card Redirect order.

  • Redirect transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

type | string

Specifies the payment flow for the checkout process. Options: direct , redirect , 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.

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.

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

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

Note: The ip_address parameter is not required, although its use is recommended to help detect fraudulent payments.

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

Creates a Credit Card Redirect order.

  • 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: 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 not 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": "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": "Request to Pay",
        "status": "initialized",
        "type": "DBRTP"
      }
    ],
    "reason": "",
    "reason_code": "",
    "related_transactions": null,
    "status": "initialized",
    "transaction_id": 36166179527,
    "payment_url": "https://pushpayments.db.com/flow/eyJwYXlsb2FkIjp7ImlwaSI6IjE2QjIwREREMjE1NjE0QTc2Rjg0OTMwMDV="
  }
}

Request to Pay

Redirect - Request to Pay

Creates a Request to Pay Redirect order.

  • Redirect transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

type | string

Specifies the payment flow for the checkout process. Options: Redirect.

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.

gateway | string

The payment gateway does not need to be specified.

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 not 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 - Request to Pay

Creates a Request to Pay Direct order.

  • Direct transaction requires all fields completed properly

  • All parameters shown are required field(s)

type | string

Specifies the payment flow for the checkout process. Options: Direct.

payment_options | object

Read more about Request to Pay 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": "pl_PL"
    }
}

JSON Response

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

Dotpay

Creates a Dotpay Redirect order.

  • Redirect transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

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 description will also be shown on the customer’s bank statement. Max. 200 characters. HTML is not 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": ""
    },
    ...
    },
    "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 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": {
            },
            "alternate": [
                {
                    "name": "none",
                    "rules": [
                        {
                            "rate": "0.00"
                        }
                    ]
                },
                {
            ]
        }
    }
}

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": {
        ...
        "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 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": {
            },
            "alternate": [
                {
                {
                    "name": "none",
                    "rules": [
                        {
                            "rate": "0.00",
                            "country": ""
                        }
                    ]
                }
            ]
        },
        "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": ""
    },
    ...
    },
    "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": "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": {
            },
            "alternate": [
                {
                    "name": "none",
                    "rules": [
                        {
                            "rate": "0.00"
                        }
                    ]
                },
            ]
        }
    }
}

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 E-invocing Direct order to be paid after delivery

  • Direct transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

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 description will also be shown on the customer’s bank statement. Max. 200 characters. HTML is not 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 lastname require minimum two characters.

delivery | object

Contains the delivery information for the shipment. _Values for first_name and lastname require minimum two characters.

shopping_cart | object

Contains all purchased items including tax class. If you are using your own integration, the transaction should be sent including the complete specification of the shopping_cart.

Please note: In order for the shopping_cart to function correctly, the shipment item requires a parameter ‘merchant_item_id’ with the value ‘msp-shipping’

items | object

Specification of products (items) which can be set in order to be displayed on the checkout page. The descriptions of the shopping cart parameters can be viewed in the shopping_cart.items API section.

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

Please note that _firstname and _lastname 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 E-Invoicing on our documentation page.

Redirect - E-invoicing

Creates an E-invoicing Redirect order to be paid after delivery.

  • Redirect transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

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 description will also be shown on the customer’s bank statement. Max. 200 characters. HTML is not 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 lastname require minimum two characters.

delivery | object

Contains the delivery information for the shipment. _Values for first_name and lastname require minimum two characters.

shopping_cart | object

Contains all purchased items including tax class. If you are using your own integration, the transaction should be sent including the complete specification of the shopping_cart.

Please note: In order for the shopping_cart to function correctly, the shipment item requires a parameter ‘merchant_item_id’ with the value ‘msp-shipping’

items | object

Specification of products (items) which can be set in order to be displayed on the checkout page. The descriptions of the shopping cart parameters can be viewed in the shopping_cart.items API section.

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

Note: The ip_address parameter is not required, although its use is recommended to help detect fraudulent payments.

Please note that _firstname and _lastname 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 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": "at_AT"
    }
}

JSON Response

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

EPS

Creates an EPS Redirect order.

  • Redirect transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

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 description will also be shown on the customer’s bank statement. Max. 200 characters. HTML is not supported. Use the ‘items’ or ‘shopping_cart’ objects for this.

payment_options | object

customer | object

Contains the personal information of the customer. _Values for first_name and lastname require minimum two characters.

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

JSON Response

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

Giropay

Creates a Giropay Redirect order.

  • Redirect transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

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 description will also be shown on the customer’s bank statement. Max. 200 characters. HTML is not supported. Use the ‘items’ or ‘shopping_cart’ objects for this.

payment_options | object

customer | object

Contains the personal information of the customer. _Values for first_name and lastname require minimum two characters.

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-1",
    "payment_url": "https://payv2.multisafepay.com/connect/99wi0OTuiCaTY2nwEiEOybWpVx8MNwrJ75c/?lang=nl_NL"
  }
}

Gift card

Creates a Gift Card Redirect order.

  • Redirect transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

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

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: nl_NL |

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.

Note: The ip_address parameter is not required, although its use is recommended to help detect fraudulent payments.

The gateway names of the standard gift cards MultiSafepay offers

Gift card name Gateway name, gift card
Baby Cadeaubon BABYCAD
Beautyandwellness BEAUTYWELL
Bloemencadeaukaart BLOEMENCAD
Boekenbon BOEKENBON
Degrotespeelgoedwinkel DEGROTESPL
Fashioncheque FASHIONCHQ
Fashiongiftcard FASHIONGFT
Fietsenbon FIETSENBON
Good4fun GOOD4FUN
Gezondheidsbon GEZONDHEID
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": "redirect",
    "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": true,
        "max_amount": 2000
        "min_amount": 500
    },
    "customer": {
        "locale": "nl_NL"
    }
}

JSON Response

{
    "success": true,
    "data": {
        "order_id": "my-order-id-1",
        "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

Creates a iDEAL QR Redirect order.

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 not available.

Please keep in mind that in case min_amount is not set, the value of amount will be used as the min_amount and vice versa. If max_amount is not set, the value of amount will be used as the max_amount for this transaction. In case both min_amount and max_amount are used, the value of amount will be disregarded.

  • Redirect transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

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 not supported. Use the ‘items’ or ‘shopping_cart’ objects for this.

payment_options | object

Contains the redirect_url, cancel_url and notification_url

customer | object

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. Requires parameter max_amount or min_amount or both. Often used for donations.

min_amount | string

With the min_amount you can specify what the minimum amount can be in case the allow_change_amount option is activated. The min_amount should not be bigger than the ‘amount’. If only min_amount is used, the ‘amount’ should be more than the min_amount, therefore the ‘amount’ = max_amount.

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. If only max_amount is used, the ‘amount’ should be less than the max_amount.

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": "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",
    "currency": "EUR",
    "amount": 1000,
    "gateway": "iDEAL",
    "description": "Test Order 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":,
        "description": "",
        "transaction_id": 77368292,
        "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": "Test Order Description",
    "fastcheckout": "NO",
    "financial_status": "initialized",
    "items": null,
    "modified": "2020-01-14T12:08:43",
    "order_id": "my-order-id-1",
    "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": "Test Order Description",
        "external_transaction_id": "1150001181473373",
        "payment_description": "iDEAL",
        "status": "initialized",
        "type": "IDEAL"
      }
    ],
    "reason": "",
    "reason_code": "",
    "related_transactions": null,
    "status": "initialized",
    "transaction_id": 77368292,
    "payment_url": "https://www.abnamro.nl/en/ideal-betalen/index.html?randomizedstring=8641247395&trxid=1150001181473373"
  }
}

iDEAL

Redirect - iDEAL

Creates a iDEAL Redirect order.

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

  • Redirect transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

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

Has to be EUR.

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

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: nl_NL |

Direct - iDEAL

Creates a iDEAL Direct order.

In the case of a Direct transaction, the customer 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.

  • Direct transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

type | string

Specifies the payment flow for the checkout process. Options: 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": "nl_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": "nl_BE",
      "first_name": "Testperson-nl",
      "last_name": "Approved",
      "address1": "Kraanspoor",
      "house_number": "39C",
      "zip_code": "1033SC",
      "city": "Amsterdam",
      "country": "NL",
      "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 - ING Home’Pay

Creates an ING Home’Pay Direct order.

  • Direct transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

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 not 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 - ING Home’Pay

Creates an ING Home’Pay Redirect order.

  • Redirect transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

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 not 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": ""
    },
    "plugin": {
        "shop": "my-shop",
        "plugin_version": "1.0.0",
        "shop_version": "1",
        "partner": "partner",
        "shop_root_url": "http://multisafepay.com"
    },
    "customer": {
        "locale": "nl_NL",
        "ip_address": "127.0.0.1",
        "forwarded_ip": "127.0.0.1",
        "first_name": "Testperson-nl",
        "last_name": "Approved",
        "address1": "Kraanspoor",
        "house_number": 39C,
        "zip_code": "1033 SC",
        "city": "Amsterdam",
        "country": "NL",
        "phone": "0612345678",
        "email": "[email protected]",
        "disable_send_email": false,
        "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"
    },
    "delivery": {
        "first_name": "Testperson-nl",
        "last_name": "Approved",
        "address1": "Kraanspoor",
        "house_number": 39C,
        "zip_code": "1033 SC",
        "city": "Amsterdam",
        "country": "NL"
    },
    "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 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": {
            "alternate": [
                {
                    "name": "none",
                    "rules": [
                        {
                            "rate": "0.00"
                        }
                    ]
                }
            ]
        }
    }
}

JSON Response

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

Klarna

Redirect - Klarna

Creates a Klarna Redirect order to be paid after delivery

Processing transactions with Klarna (the old environment) is only available as a Redirect request.

Klarna Payments (the new environment of Klarna) is available as a Redirect request, although you may use the Direct request if you have your own integration. The JSON request remains the same for both Klarna and Klarna payments.

  • Redirect transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

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 not 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 lastname require minimum two characters.

delivery | object

Contains the delivery information for the shipment. _Values for first_name and lastname require minimum two characters.

shopping_cart | object

Contains all purchased items including tax class. If you are using your own integration, the transaction should be sent including the complete specification of the shopping_cart.

Please note: In order for the shopping_cart to function correctly, the shipment item requires a parameter ‘merchant_item_id’ with the value ‘msp-shipping’

items | object

Specification of products (items) which can be set in order to be displayed on the checkout page. The descriptions of the shopping cart parameters can be viewed in the shopping_cart.items API section.

quantity | integer

The quantity of a specific item in the shopping cart. Decimals are not accepted and the value should be stated as a whole number e.g. ‘13’

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 to which the system can send payment instructions to the customer.

gender | string

The gender of the customer. (Required for Klarna, optional for Pay After Delivery and E-Invoicing) Options: male, female.

ip_address | string

The IP address of the customer. “Required” with post payment and credit card payment methods. Due to validation of the customer IP address, we need to receive the actual IP address of the end user within the ip_address field. More info

forwarded_ip | string

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

Please note that first_name and last_name in both customer and delivery objects require minimum two characters per entry. Failing to do so might result in unexpected errors. Given the nature of this payment method, we recommend you to always require full names (not initials, abbreviations, acronyms).

Read more about Klarna on our documentation page.

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

  • Redirect transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

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 not 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 lastname require minimum two characters.

delivery | object

Contains the delivery information for the shipment. _Values for first_name and lastname require minimum two characters.

shopping_cart | object

Contains all purchased items including tax class. If you are using your own integration, the transaction should be sent including the complete specification of the shopping_cart.

Please note: In order for the shopping_cart to function correctly, the shipment item requires a parameter ‘merchant_item_id’ with the value ‘msp-shipping’

items | object

Specification of products (items) which can be set in order to be displayed on the checkout page. The descriptions of the shopping cart parameters can be viewed in the shopping_cart.items API section.

unit_price | float

The unit price (in decimals) of the specific product excluding VAT. A maximum of 10 decimal places is accepted.

quantity | integer

The quantity of a specific item in the shopping cart. Decimals are not accepted and the value should be stated as a whole number e.g. ‘13’

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 to which the system can send payment instructions to the customer.

ip_address | string

The IP address of the customer. “Required” with post payment and credit card payment methods. Due to validation of the customer IP address, we need to receive the actual IP address of the end user within the ip_address field. More info

forwarded_ip | string

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

Please note that first_name and last_name in both customer and delivery objects require minimum two characters per entry. Failing to do so might result in unexpected errors. Given the nature of this payment method, we recommend you to always require full names (not initials, abbreviations, acronyms).

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": "nl_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",
    "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_BE",
        "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 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",
      "city": "Amsterdam",
      "country": "NL",
      "country_name": null,
      "email": "[email protected]",
      "first_name": "Testperson-nl",
      "house_number": 39C,
      "last_name": "Approved",
      "phone1": "0208500500",
      "locale": "nl_BE",
      "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 - KBC

Creates a KBC Redirect order.

  • Redirect transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

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 not 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 - KBC

Creates a KBC Direct order.

  • Direct transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

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

Note: The ip_address parameter is not required, although its use is recommended to help detect fraudulent payments.

Read more about KBC on our documentation 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

Creates a Maestro Redirect order.

  • Redirect transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

type | string

Specifies the payment flow for the checkout process. Options: redirect.

gateway | string

Fixed value: MAESTRO

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

Note: The ip_address and e-mail address parameters are not required, although their use is recommended to help detect fraudulent payments.

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

Creates a Mastercard Redirect order.

Besides the individual credit card gateways, MultiSafepay offers you a generic gateway called CREDITCARD. This can save space on your mobile checkout. The disadvantage is that the customer can not immediately see which credit cards can be used. The correct credit card logo will appear automatically when the card holder provides the first digits of the credit card number.

  • Redirect transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

type | string

Specifies the payment flow for the checkout process. Options: redirect.

gateway | string

Fixed value: 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 description will also be shown on the customer’s bank statement. Max. 200 characters. HTML is not 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.

Note: The ip_address and e-mail address parameters are not required, although their use is recommended to help detect fraudulent payments.

Read more about Mastercard 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": ""
    },
...
    "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 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": {
            },
            "alternate": [
                {
                    "name": "none",
                    "rules": [
                        {
                            "rate": "0.00"
                        }
                    ]
                }
            ]
        }
    }
}

JSON Response

{
  "success": true,
  "data": {
    "order_id": "my-order-id-1",
    "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": ""
    },
    ...
    "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"
                }
            },
        ]
    },
    "checkout_options": {
        "tax_tables": {
            "alternate": [
                {
                    "name": "none",
                    "rules": [
                        {
                            "rate": "0.00"
                        }
                    ]
                }
            ]
        }
    }
}

JSON Response

{
  "success": true,
  "data": {
    "amount": 26000,
    "amount_refunded": 0,
    "checkout_options": {
      "alternate": [
        {
          "name": "none",
          "rules": [
            {
              "country": "",
              "rate": "0.00"
            }
          ]
        }
      ],
      "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": {
    },
    ...
    
    "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 Pay After Delivery Redirect order.

  • Redirect transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

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: 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 description will also be shown on the customer’s bank statement. Max. 200 characters. HTML is not supported. Use the ‘items’ or ‘shopping_cart’ objects 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 lastname require minimum two characters.

delivery | object

Contains the delivery information for the shipment. _Values for first_name and lastname require minimum two characters.

shopping_cart | object

Contains all purchased items including tax class. If you are using your own integration, the transaction should be sent including the complete specification of the shopping_cart.

Please note: In order for the shopping_cart to function correctly, the shipment item requires a parameter ‘merchant_item_id’ with the value ‘msp-shipping’

items | object

Specification of products (items) which can be set in order to be displayed on the checkout page. The descriptions of the shopping cart parameters can be viewed in the shopping_cart.items API section.

checkout_options | object

Contains the definitions for the VAT class.

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 to which the system can send payment instructions to the customer.

ip_address | string

The IP address of the customer. “Required” with post payment and credit card payment methods. Due to validation of the customer IP address, we need to receive the actual IP address of the end user within the ip_address field. More info

forwarded_ip | string

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

Please note that _firstname and _lastname 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 Pay After Delivery on our documentation page.

Direct - Pay After Delivery

Creates a Pay After Delivery Direct order.

  • Direct transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

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: 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 description will also be shown on the customer’s bank statement. Max. 200 characters. HTML is not supported. Use the ‘items’ or ‘shopping_cart’ objects 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 lastname require minimum two characters.

delivery | object

Contains the delivery information for the shipment. _Values for first_name and lastname require minimum two characters.

shopping_cart | object

Contains all purchased items including tax class. If you are using your own integration, the transaction should be sent including the complete specification of the shopping_cart.

Please note: In order for the shopping_cart to function correctly, the shipment item requires a parameter ‘merchant_item_id’ with the value ‘msp-shipping’

items | object

Specification of products (items) which can be set in order to be displayed on the checkout page. The descriptions of the shopping cart parameters can be viewed in the shopping_cart.items API section.

checkout_options | object

Contains the definitions for the VAT class.

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 to which the system can send payment instructions to the customer.

ip_address | string

The IP address of the customer. “Required” with post payment and credit card payment methods. Due to validation of the customer IP address, we need to receive the actual IP address of the end user within the ip_address field. More info

forwarded_ip | string

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

Please note that _firstname and _lastname 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 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": "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": "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": "1033SC",
        "city": "Amsterdam",
        "state": "NH",
        "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",
      "city": "Amsterdam",
      "state": "NH",
      "country": "NL",
      "email": "[email protected]",
      "first_name": "Testperson-nl",
      "house_number": "39C",
      "last_name": "Approved",
      "locale": "nl_NL",
      "phone1": "0208500500",
      "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 - PayPal

Creates a PayPal Redirect order.

In PayPal, after a successful payment of a transaction, the order status is set to Completed and the financial status remains set to Initialized. If the financial status remains Initialized, an order cannot be delivered since the shipment of an order depends on the financial status. You must ensure that orders are set to Completed for both the order and financial status after a successful payment.

  • Redirect transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

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: 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 description will also be shown on the customer’s bank statement. Max. 200 characters. HTML is not 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.

state | string

To be eligible for PayPal Seller Protection, the transaction request needs to have the correct state in the customer address details for the following countries

Read more about PayPal on our documentation page.

Direct - PayPal

Creates a PayPal Direct order.

  • Direct transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

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: 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 description will also be shown on the customer’s bank statement. Max. 200 characters. HTML is not 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.

state | string

To be eligible for PayPal Seller Protection, the transaction request needs to have the correct state in the customer address details for the following countries

Note: The ip_address parameter is not required, although its use is recommended to help detect fraudulent payments.

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": "nl_NL",
        "ip_address": "31.148.195.10",
        "forwarded_ip": "",
        "first_name": "Testperson-nl",
        "last_name": "Approved",
        "address1": "Kraanspoor",
        "house_number": "39C",
        "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": {
        "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": "nl_NL",
        ...
        },
        "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 Betaal per Maand

Creates a Santander Betaal per Maand Direct order.

  • Direct transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

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.

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 not supported. Use the ‘items’ or ‘shopping_cart’ objects 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 lastname 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

Note: The ip_address parameter is not required, although its use is recommended to help detect fraudulent payments.

Please note that _firstname and _lastname 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 Betaal per Maand 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": "Example",
        "account_holder_iban": "NL87ABNA0000000001",
        "emandate": "mandateID"
    }
}

JSON Response

{
  "success": true,
  "data": {
    "transaction_id": 259898679,
    "order_id": "my-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",
 ...
    },
    "payment_details": {
      "recurring_id": "",
      "type": "DIRDEB",
      "account_id": "NL87ABNA0000000001",
      "account_holder_name": "Example",
      "external_transaction_id": "6190662598986790",
      "account_iban": "NL87ABNA0000000001",
    },
    "costs": [
      {
        "transaction_id": 279354751,
        "description": "0.0 For SEPA Direct Debit Transactions",
        "type": "SYSTEM",
        "amount": 0.0
      }
    ],
    "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 - SEPA Direct Debit

Creates a SEPA Direct Debit Redirect order.

The recurring_id parameter can be used to process subsequent payments when the recurring option is enabled in your MultiSafepay Control. The recurring_id must be included in the gateway info section of the request. Read more about recurring payments

  • Redirect transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

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.

recurring_id | string

The recurring_id is a unique id that can be used to process subsequent payments.

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

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 - SEPA Direct Debit

Creates a SEPA Direct Debit Direct order.

  • Direct transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

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 description will also be shown on the customer’s bank statement. Max. 200 characters. HTML is not 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

Note: The ip_address parameter is not required, although its use is recommended to help detect fraudulent payments.

Read more about SEPA Direct Debit 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",
      "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 - SOFORT

Creates a SOFORT Redirect order.

  • Redirect transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

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: 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. Check out the availble currencies in this page

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 not 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 lastname require minimum two characters.

Read more about SOFORT Banking on our documentation page.

Direct - SOFORT

Creates a SOFORT Direct order.

  • Direct transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

type | string

Specifies the payment flow for the checkout process. Options: direct. |

gateway | string

The unique gateway id to immediately direct the customer to the payment method. You retrieve these gateways using a gateway request. Options: 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. Check out the availble currencies in this page

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 not 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 lastname require minimum two characters.

Note: The ip_address parameter is not required, although its use is recommended to help detect fraudulent payments.

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

Creates a Trustly Redirect order.

  • Redirect transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

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 description will also be shown on the customer’s bank statement. Max. 200 characters. HTML is not 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.

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": "TRUSTPAY",
    "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": {
        "email": "[email protected]"
        "locale": "cs_CZ"
    }
}

JSON Response

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

TrustPay

Creates a TrustPay Redirect order.

  • Redirect transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

type | string

Specifies the payment flow for the checkout process. Options: redirect.

gateway | string

TRUSTPAY

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

customer | object

email | string

Customer’s provided email address. Used to send Second Chance emails, in fraud checks and the sending bank transfer email.

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.

Read more about TrustPay 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

Creates a Visa Redirect order.

Besides the individual credit card gateways, MultiSafepay offers you a generic gateway called CREDITCARD. This can save space on your mobile checkout. The disadvantage is that the customer can not immediately see which credit cards can be used. The correct credit card logo will appear automatically when the card holder provides the first digits of the credit card number.

  • Redirect transaction requires all fields completed properly

  • All parameters shown are required field(s)

Parameters

type | string

Specifies the payment flow for the checkout process. Options: redirect.

gateway | string

Fixed value: VISA

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

Note: The ip_address and e-mail address parameters are not required, although their use is recommended to help detect fraudulent payments.

Read more about Visa on our documentation page.

Transactions

PATCH - /orders

{
    "status": "cancelled",
    "exclude_order": 1
}

JSON Response

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

Cancel pre-transaction (sessionid)

Cancellation of a transaction based on a sessionid

Parameters

status | string

The status of the order. Options: cancelled

exclude_order | integer

Indicates the outcome of the cancellation. When exclude_order is set to 1, the pre-transaction (sessionid) will be cancelled. When exclude_order is set to 0, the pre-transaction will be cancelled as well as the transaction itself. Please note: this only works if transactions are marked as ‘Initialized’. A ‘Reserved’ status cannot be cancelled.

POST - /orders/{order_id}/refunds

{
    "order_id": "my-order-id-1",
    "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

Parameters

order_id | integer / string

The order_id of the order you want to refund.

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 when the current balance of a 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": "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:

  1. A request should be done to GET - /orders/{id} to obtain the cart items of the order and possible refunded items
  2. 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”.
  3. 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

checkout_data | object

Contains the original shopping cart + copied items to be refunded.

Other Requests

GET - /categories

JSON Response

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

Categories

Returns a list of website categories.

POST - /orders/{order_id}/files

{
    "type": "",
    "base64": "",
    "description": "",
    "name": ""
}

JSON Response

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

Chargeback

MultiSafepay can challenge the chargeback on your behalf, but to do so, we need documented proof of the order.

You can upload the files or documents via an API request or contact our support team at [email protected]

Read more about chargebacks on our documentation page.

Parameters

type | string

Specifies the payment flow for the checkout process. Options: chargeback.

base64 | string

Binary Base 64 encoded. Upload images “pdf, jpeg and png”.

description | integer

Description or comments of the submitted file.

name | string

Name of the file.

Reference

"locale": "nl_NL",
"ip_address": "31.148.195.10",
"forwarded_ip": "",
"first_name": "customer's first name",
"last_name": "customer's last name",
"gender": "",
"birthday": "",
"address1": "Kraanspoor",
"address2": "customer's address",
"house_number": "39",
"zip_code": "1033SC",
"city": "Amsterdam",
"country": "Netherlands",
"phone": "0208500500",
"email": "[email protected]",
"user_agent": "Mozilla/5.0 (Windows NT 6.3; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/38.0.2125.111 Safari/537.36",
"referrer": "http://example.com"

customer, object

locale

Parameter

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

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

forwarded_ip | string

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

first_name

Parameter

first_name | string

The customer’s first name.

last_name

Parameter

last_name | string

The customer’s last name.

gender

Parameter

gender | string

The customer’s gender.

birthday

Parameter

birthday | string

The customer’s birthday.

address1

Parameter

address1 | string

First line of customer’s provided address.

address2

Parameter

address2 | string

Second line of customer’s provided address.

house_number

Parameter

house_number | string

Customer’s provided house number.

zip_code

Parameter

zip_code | string

Customer’s provided zip / postal code.

city

Parameter

city | string

Customer’s provided city.

country

Parameter

country | string

Customer’s provided country code ISO 3166-1

phone

Parameter

phone | string

Customer’s provided phone number.

email

Parameter

email | string

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

user_agent

Parameter

user_agent | string

A characteristic string that identifies a browser.

referrer

Parameter

referrer | string

Identification of where the user/browser is originating from.

"days_active": 30,
"seconds_active": 60,
"description": "Test Order Description",

days_active / seconds_active

The days or seconds active indicates the lifetime of a payment link.

  • If seconds_active is sent in the API request and larger than 0, then seconds_active will be used
  • If days_active is sent in the API request then days_active is used
  • If nothing is sent, then 30 days will be set by default
  • If both seconds_active and days_active are sent in the API request, then seconds_active is used if the value is larger than 0.

The full documentation can be found on our FAQ page, The lifetime of a payment link

Parameters

days_active | string

The number of days the payment link will be active for. Default is 30.

seconds_active | string

The number of seconds the payment link will be active for. Default is 30 days.

description | string

A text that can be added to the order. The text will be printed on the bank statement of the customer, within the limits of their bank. Please note: MultiSafepay will remove all html tags and cut the remaining text at 200 charachters

 "second_chance": {
   "send_email": true
},

Second Chance

If the customer didn’t finish the payment, you can send a reminder in the form of a payment link.

As per GDPR requirements, MultiSafepay does not submit emails by default. Please ensure that when enabling this option, there is a documented consent from the receiver for submitting an email related to the respective payment link.

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.

Parameters

second_chance | object

Sends a payment reminder to the customer in the form of an email.

send_email | boolean

Sends a Second Chance reminder in the form of an email to the customer when set to true. When set to false or left empty, no email reminder will be sent.

Suppress Email Second Chance after cancellation

When a customer makes an order, goes to the checkout page but returns, and tries again, some webshops create a second order. If the second chance is on, the customer will receive emails for the first order, even when the second order is paid.

Cancellation of the first order doesn’t suppress the second chance email.

To suppress the second chance email you have to add these parameters in the update of the order:

"status": "cancelled",
"exclude_order": 1

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:

  1. Card on file (COF): transaction where a cardholder authorized a merchant to store the cardholder’s details

  2. Subscription: agreement or services that are billed at the end of a merchant’s billing cycle

  3. Unscheduled: event triggered for application (for example a mobile top up when no credit is left on the phone)

  • All parameters shown are required field(s)

Parameters

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

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.

_It must be noted that the recurring_id, recurringmodel and reference must be specified in the request in order for the transaction to be processed

  • All parameters shown are required field(s)

Parameters

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.

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

account_holder_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": {
		"tokens": [{
				"token": "QZTCh7jdk8",
				"code": "MASTERCARD",
				"display": "1234 5678 9101 2345",
				"bin": 555555,
				"name_holder": "Test-person-nl",
				"expiry_date": 0988,
				"expired": 0,
				"last4": 1111,
				"recurring_model": "cardOnFile"
			},
			{
				"token": "GVXjq3432o4",
				"code": "VISA",
				"display": "1234 5678 9101 2345",
				"bin": 411111,
				"name_holder": "WebcashierE2E",
				"expiry_date": 0988,
				"expired": 0,
				"last4": 2222,
				"recurring_model": "unscheduled"
			}
		]
	}
}

List all tokens for a customer reference

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

If you have many tokens, you can use the two parameters limit and offset to limit the number of tokens that will be listed.

Example: If the limit is set to 15 and the offset to 0, then 17 tokens will be listed (token 0 to token 16)

  • All parameters shown are required field(s)

Parameter

token | string

The unique token linked to the customer reference.

limit | integer

The number of tokens listed. If limit is empty, the default value is 10.

offset | integer

The position from which the tokens will be listed. If offset is left empty, the default value is 0 (the first token)

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

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

token | string

The unique token linked to the customer reference.

    "items": "<ol><li>Article 1: € 1,95</li><li>Article 2: € 2,95</li><li>Article 3: € 3,95</li></ol>",

Order specification with “items”

The line “items” can be added to the JSON request. Post payment methods require the full shopping_cart.

Parameter

items | object

Specification of products (items) which can be set in order to be displayed on the checkout page.

"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

Parameters

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.

notification_method | string

Enables push notifications (POST,GET) default: GET.

close_window | bool

Options: true, false. Set to true if you want to display the MultiSafepay payment page in a new window and want to close it automatically after the payment process.

"name": "",
"description": "",
"unit_price": "",
"quantity": "",
"merchant_item_id": "",
"tax_table_selector": "",
"weight": {},
"options": [],
"value": "",
"unit": "",

shopping_cart.items

name

Parameter Type Description
name string The customer’s name

description

Parameter Type Description
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 not supported. Use the ‘items’ or ‘shopping_cart’ objects for this.

unit_price

Parameter Type Description
unit_price float The unit price (in decimals) of the specific product excluding VAT. A maximum of 10 decimal places is accepted.

quantity

Parameter Type Description
quantity integer The number of items for a specific item in the shopping cart.

merchant_item_id

Parameter Type Description
merchant_item_id string A unique ID relating to the specified item in the shopping cart.

tax_table_selector

Parameter Type Description
tax_table_selector string The tax ruling specified. Please note that if the tax_table_selector is 0 an error will be displayed: ‘1029: Invalid tax rate specified for item’. In addition to this, the tax_table_selector and tax_table names are both strings.

weight

Parameter Type Description
weight object The weight of the item in the shopping cart.

options

Parameter Type Description
options string An array of objects including id, set_id, value, price, type and price_type.

value

Parameter Type Description
value integer The weight of an item corresponding to the unit. For example unit: KG, value: 12. Thus the weight of the item is 12 kilograms.

unit

Parameter Type Description
unit string The unit used to measure the weight of the item e.g. KG

PATCH - recurring/{your_customer_reference}/update/{your_token}

{
    "expiry_date": "2903"
}

JSON response

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

Update credit card expiry date of a token

This API call allows you to update the credit card expiry date of a token for when it has expired.

Use PATCH with the required placeholders in the URL:

  • your_customer_reference refers to your internal unique customer reference
  • your_token refers to the unique token associated with the customer

expiry_date | integer

The updated value of the expiry date. E.g., December 2025 is formatted as 1225

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.

Parameters

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": "https://multisafepay.com"
}

Financial Statuses

Transactions can have the following financial statuses:

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

Status Description
Initialized A payment link has been generated, but no payment has yet been received.
Uncleared The payment is completed, but funds are still underway.
Completed The payment is finished and the funds are available for payout.
Declined Rejected by the the issuing bank and no funds will arrive. Read more about the reason why the transaction is declined in what does it mean
Cancelled Cancelled by the merchant and no funds will arrive.
Void Cancelled by the merchant and no funds will arrive.
Expired Depending on the payment method, unfinished transactions will close automatically after a predefined period.
Reserved Payout / refund has been put on reserved, a temporary status, until the merchant’s account has been checked on sufficient balance.

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. 
"custom_info": {
      "custom_1": null,
      "custom_2": null,
      "custom_3": null

custom_info

custom_info is a ‘placeholder’ where the merchant can input specific data related to the transaction. 

    
    "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 credit card logos
hide_btn_all_methods Hides all methods button

Read more about dynamic styling for a payment page.

Tools

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

Parameters

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 description will also be shown on the customer’s bank statement. Max. 200 characters. HTML is not 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.

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

Parameters

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 description will also be shown on the customer’s bank statement. Max. 200 characters. HTML is not 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.

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

Parameters

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 description will also be shown on the customer’s bank statement. Max. 200 characters. HTML is not 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.

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

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.

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.

Please note: MultiSafepay no longer supports Flexible 3D with merchants based in Europe due to PSD2 regulations.

Parameters

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 description will also be shown on the customer’s bank statement. Max. 200 characters. HTML is not 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.

Please note: MultiSafepay no longer supports Flexible 3D with merchants based in Europe due to PSD2 regulations.

Parameters

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 description will also be shown on the customer’s bank statement. Max. 200 characters. HTML is not 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.

Credit card transactions which are processed with the 3D Secure protocol require a form of authentication of the customer during the payment process. Setting Flexible 3D to false will disable the verfication process.

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

Please note: MultiSafepay no longer supports Flexible 3D with merchants based in Europe due to PSD2 regulations.

Parameters

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 description will also be shown on the customer’s bank statement. Max. 200 characters. HTML is not 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

First line of customer’s provided house number.

zip_code | string

First line of customer’s provided zip_code / 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",
    "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.

Parameters

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. 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 description will also be shown on the customer’s bank statement. Max. 200 characters. HTML is not 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. 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

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(/faq/general/glossary/#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.

Please note: MultiSafepay no longer supports Flexible 3D with merchants based in Europe due to PSD2 regulations.

Parameters

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 description will also be shown on the customer’s bank statement. Max. 200 characters. HTML is not 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

First line of customer’s provided house number.

zip_code | string

First line of customer’s provided zip_code / 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/{order_id}/capture

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

JSON Response

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

Partial Capture

Parameter

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.

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.

POST - /orders/{order_id}/capture

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

JSON Response

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

Full Capture

Parameters

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.

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

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.

GET - /orders/{order_id}

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

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/{order_id}

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

JSON Response

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

Cancel Authorization / Reservation

Parameters

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",
    "second_chance": { 
        "send_email" : true
    },
    "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"
  }
}

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.

Second Chance

Second Chance is an email reminder that points out to your customers of their attempted (and incomplete) payment(s) and encourages them to finalize the payment(s).

As per GDPR requirements, MultiSafepay does not submit emails by default. If you enable this option, please ensure there is a documented consent from the recipient of the payment link.

Please note: Payment links will no longer send Second Chance emails by default. It is the responsibility of the merchant to include the Second Chance script in the JSON request. See the Second Chance JSON script on the right-hand side.

Parameters

type | string

Specifies the payment flow for the checkout process. Fill in ‘paymentlink’. It must be noted that orders with “type”: “paymentlink” will be visible in the MultiSafepay Control under Tools > Payment link generator

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 (optional) | 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 not supported. Use the ‘items’ or ‘shopping_cart’ objects for this.

second_chance (optional) | object

Sends a payment reminder to the customer in the form of an email.

send_email (optional) | boolean

Sends a Second Chance reminder in the form of an email to the customer when set to true. When set to false or left empty, no email reminder will be sent.

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.

Parameters

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. Required. (max. 50 chars).

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

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.

Feedback

You're missing something out and would like us to fix it? Suggest an improvement to this page!

Feedback

Other languages

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

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

Falls Sie eine deutschsprachige Erklärung bevorzugen, kontaktieren Sie bitte Ihren Kundenbetreuer.

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

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