API Reference

 

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 API - https://testapi.multisafepay.com/v1/json/
Live API - https://api.multisafepay.com/v1/json/

Authentication

All requests to the MultiSafepay API require authentication. Authentication is provided by including an API Key as an HTTP header in your request. Each website has it's own API Key so if you are operating multiple websites be sure to use the correct API Key for each site. The API Key can be found under the website settings in MultiSafepay Control.

The HTTP header name for the API Key is: api_key

Localization

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.

Example
GET - /gateways?locale=es 
	
$msp->gateways->get($endpoint= 'gateways', $type= '', array(), $query_string);
new MultiSafepayClient(
	"{apiKey}", "{apiUrl}", "{langaugeCode}"
);
MspClient.sendRequest("gateways?locale={locale}");

Retrieve all gateways

country : optional
Specify an ISO 3166-1 country code to filter out payment gateways that are not applicable for the specified country. This can be used to simplify the list of payment options presented to the customer by removing payment methods specific to other countries e.g. giropay or iDEAL.

currency: optional
Specify an ISO 4217 currency code to filter out payment gateways that are not applicable for the specified currency. This can be used to simplify the list of payment options presented to the customer by only displaying payment methods supported by the transaction currency. e.g. Credit Cards

amount: optional
Specify the transaction amount (in cents) to filter out payment gateways that are not applicable for that amount. This is commonly used to exclude Pay After Delivery as a payment option for very small, or large, amounts but can also be configured to exclude other payment methods.

Example
GET - /gateways?
	country={country_code}
	&currency={currency_code}
	&amount={amount}
	
$gateways = $msp->gateways->get();
client.GetGateways(
	"{countryCode}", "{currencyCode}", {amount}
);
MultiSafepayClient.GetGateways();

Retrieve a gateway

id: required
The unique identifier of the gateway to be returned.

Example
GET - /gateways/{id}
	
client.GetGateway("{id}")
MultiSafepayClient.GetGateway("{gateway}")

Retrieve issuers for gateway

id: required
The unique identifier of the payment gateway to retrieve an issuer list for. Currently supported identifiers are: iDEAL.

Example
GET - /issuers/{id}
	
$msp->issuers->get();
client.GetIssuers("iDEAL")
MultiSafepayClient.GetIssuer("{id}");

Create an order

type: required
Specifies the payment flow for the checkout process. For normal orders use the value "redirect".

order_id: required
The unique identifier from your system for the order.

currency: required
The currency you want the customer to pay with.

amount: required
The amount (in cents) that the customer needs to pay.

description: required
A free text description which will be shown with the order in MultiSafepay Control. If the customers bank supports it this description will also be shown on the customers bank statement.

gateway: optional
The unique gateway id to immediately direct the customer to the payment method. You retrieve these gateways using a gateway request. 

var1, var2, var3: optional

A free variable for custom data to be stored and persisted.

items: optional
Include an HTML formatted list of the items ordered. Used to customer how the order is displayed on payment pages and emails.

manual: optional
If true this forces a credit card transaction to require manual acceptance regardless of the outcome from fraud checks. It is possible that a high risk transaction is still declined.

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

payment_options: required

notification_url: required
The URL that MultiSafepay will send transaction status updates to when the status of a transaction changes.

redirect_url: required
Where we will direct a customer from our payment pages after a successful transaction.

cancel_url: required
Where we will direct a customer from our payment pages after a cancelled or unsuccessful transaction.

close_window: optional
Set to true if you will display the MultiSafepay payment page in a new window and want it to close automatically after the payment process has been completed.

customer: optional (recommended)
Without receiving customer data we are not able to do an external check on credit card transactions.

locale: optional
Include to provide localized payment pages for the customer. Use the format ab_CD with ISO 639 language codes and ISO 3166 country codes.

ip_address: optional
The IP address of the customer.

forwarded_ip: optional
The X-FORWARED-FOR header of the customer request when using a proxy.

referrer: optional
The address of the page (if any) which referred the user agent to the current page..

user_agent: optional
Contents of the  User-Agent:  header from the current request, if there is one. This is a string denoting the user agent being which is accessing the page. A typical example is:  Mozilla/4.5 [en] (X11; U; Linux 2.2.9 i586)

first_name: optional (recommended)
The customer's first name. 

last_name: optional (recommended)
The customer's last name. 

address1: optional (recommended)
First line of customer's provided address.  

address2: optional
Second line of customer's provided address.  

house_number: optional (recommended)
Customer's provided house number.  

zip_code: optional (recommended)
Customer's provided zip / postal code.  

city: optional (recommended)
Customer's provided city.  

state: optional (recommended)
Customer's provided state / province.  

country: optional (recommended)
Customer's provided country.  

phone: optional
Customer's provided phone number.  

email: optional (recommended)
Customer's provided email address. Used to send second chance emails and in fraud checks.

disable_send_email: optional
True if you will send your own bank transfer payment instructions to consumers and do not want MultiSafepay to do this.

google_analytics: optional
Your Google Analytics Site Id. This will be injected into the payment pages so you can trigger custom events and track payment metrics.

Example
POST - /orders
{
    "type": "redirect",
    "order_id": null,
    "currency": null,
    "amount": null,
	"gateway": null,
    "description": null,
    "var1": null,
    "var2": null,
    "var3": null,
    "items": null,
    "manual": null,
    "days_active": null,
    "payment_options": {
        "notification_url": null,
        "redirect_url": null,
        "cancel_url": null,
        "close_window": true
    },
    "customer": {
        "locale": null,
        "ip_address": null,
        "forwarded_ip": null,
        "first_name": null,
        "last_name": null,
        "address1": null,
        "address2": null,
        "house_number": null,
        "zip_code": null,
        "city": null,
        "state": null,
        "country": null,
        "phone": null,
        "email": null,
        "disable_send_email": null,
		"user_agent":null,
		"referrer": null
    },
    "google_analytics": {
        "account": "UA-XXXXXXXXX"
    }
}
	
$order = $msp->orders->post(array(
	"type" => "redirect",
	"id" => "{orderId},
	"currency" => "{currencyCode}",
	"amount" => {amount},
	"description" => "{description}",
	"payment_options" => array(
		"notification_url" => "{notificationUrl}",
		"redirect_url" => "{successRedirectUrl}",
		"cancel_url" => "{cancelledRedirectUrl}"
	)
));
client.CreateOrder(
	OrderRequest.CreateRedirect(
		{orderId}, "{description}", {amount}, "{currencyCode}",
		new PaymentOptions(
			"{notificationUrl}", 
			"{successRedirectUrl}", 
			"{cancelledRedirectUrl}"
		)
	)
);
MultiSafepayClient.createOrder(
	order.setRedirect(
    	"{order_id}", 
    	"{description}", 
    	{amount}, 
    	"{currency}", 
    	new PaymentOptions("{notification_url}", "{cancel_url}", "{redirect_url}")
    ));

Create a direct order

type: required
Specifies the payment flow for the checkout process. For payment methods which support a direct transfer to the payment environment you can use the value "direct". Direct payments are only support for iDEAL, Direct Debit, PayPal, Recurring and BankTransfer.

order_id: required
The unique identifier from your system for the order.

recurring_id: optional
A previously stored recurring_id referring to a payment method to be charged again.

gateway: required
The unique gateway id to immediately direct the customer to the payment method. You retrieve these gateways using a gateway request. Supported gateway ids for direct transactions are: IDEAL, BANKTRANS, DIRDEB, PAYAFTER, PAYPAL.

currency: required
The currency you want the customer to pay with.

amount: required
The unique identifier from your system for the order.

description: required
A free text description which will be shown with the order in MultiSafepay Control. If the customers bank supports it this description will also be shown on the customers bank statement.

var1, var2, var3: optional
A free variable for custom data to be stored and persisted.

items: optional
Include an HTML formatted list of the items ordered. Used to customer how the order is displayed on payment pages and emails.

manual: optional
If true this forces a credit card transaction to require manual acceptance regardless of the outcome from fraud checks. It is possible that a high risk transaction is still declined.

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

gateway_info: required

Based on the Payment Method used, the following data needs to be set:

issuer_id -> Used for iDEAL and contains the banks issuer ID.

account_id -> Used for Direct Debit/Banktransfer and contains the IBAN number

account_holder_name -> Used for Direct Debit

account_holder_city -> Used for Direct Debit

account_holder_country ->Used for Direct Debit

account_holder_iban -> Used for Direct Debit

account_holder_bic -> Used for Direct Debit

emandate -> Used for Direct Debit

payment_options: required

notification_url: required
The URL that MultiSafepay will send transaction status updates to when the status of a transaction changes.

redirect_url: required
Where we will direct a customer from our payment pages after a successful transaction.

cancel_url: required
Where we will direct a customer from our payment pages after a cancelled or unsuccessful transaction.

close_window: optional
Set to true if you will display the MultiSafepay payment page in a new window and want it to close automatically after the payment process has been completed.

customer: optional (recommended)
Without receiving customer data we are not able to do an external check on credit card transactions. 

locale: optional
Include to provide localized payment pages for the customer. Use the format AB_cd with ISO 639 language codes and ISO 3166 country codes.

ip_address: optional
The IP address of the customer.

forwarded_ip: optional
The X-FORWARED-FOR header of the customer request when using a proxy.

referrer: optional
The address of the page (if any) which referred the user agent to the current page..

user_agent: optional
Contents of the User-Agent: header from the current request, if there is one. This is a string denoting the user agent being which is accessing the page. A typical example is: Mozilla/4.5 [en] (X11; U; Linux 2.2.9 i586)

first_name: optional (recommended)
The customer's first name.

last_name: optional (recommended)
The customer's last name.

address1: optional (recommended)
First line of customer's provided address.

address2: optional
Second line of customer's provided address.

house_number: optional (recommended)
Customer's provided house number.

zip_code: optional (recommended)
Customer's provided zip / postal code.

city: optional (recommended)
Customer's provided city.

state: optional
Customer's provided state / province.

country: optional (recommended)
Customer's provided country.

phone: optional
Customer's provided phone number.

email: optional (recommended)
Customer's provided email address. Used to send second chance emails and in fraud checks.

disable_send_email: optional
True if you will send your own bank transfer payment instructions to consumers and do not want MultiSafepay to do this.

google_analytics: optional
Your Google Analytics Site Id. This will be injected into the payment pages so you can trigger custom events and track payment metrics.

Example
POST - /orders
{
	"type": "direct",
	"order_id": null,
	"recurring_id": null,
	"gateway": null,
	"currency": null,
	"amount": null,
	"description": null,
	"var1": null,
	"var2": null,
	"var3": null,
	"items": null,
	"gateway_info": {
		"issuer_id": null
		"account_id": "",
		"account_holder_name": "",
		"account_holder_city": "",
		"account_holder_country": "",
        "account_holder_iban": "",
        "account_holder_bic": "",
        "emandate" : "madateID"
	},
	"payment_options" : {
		"notification_url": null,
		"redirect_url": null,
		"cancel_url": null,
		"close_window": "true"
	},
	"customer": {
		"locale": null,
		"ip_address": null,
		"forwarded_ip": null,
		"first_name": null,
		"last_name": null,
		"address1": null,
		"address2": null,
		"house_number": null,
		"zip_code": null,
		"city": null,
		"state": null,
		"country": null,
		"phone": null,
		"email": null,
		"disable_send_email": null,
		"user_agent": null,
		"referrer": null
	},
	"google_analytics" : {
		"account": "UA-XXXXXXXXX",
	}
}
	
$order = $msp->orders->post(array(
	"type" => "direct",
	"id" => "{orderId},
	"currency" => "{currencyCode}",
	"amount" => {amount},
	"description" => "{description}",
	"gateway" => "IDEAL",
	"gateway_info" => array(
		"issuer_id" => "{issuerId}"
	),
	"payment_options" => array(
		"notification_url" => "{notificationUrl}",
		"redirect_url" => "{successRedirectUrl}",
		"cancel_url" => "{cancelledRedirectUrl}"
	)
));
client.CreateOrder(
	OrderRequest.CreateDirectIdeal(
		"{issuerId}", {orderId}, "{description}",
		{amount}, "{currencyCode}",
		new PaymentOptions(
			"{notificationUrl}", 
			"{successRedirectUrl}", 
			"{cancelledRedirectUrl}"
		)
	)
);
MultiSafepayClient.createOrder(
	order.setDirectBank(
    	"{order_id}", 
    	"{description}", 
    	{amount}, 
    	"{currency}", 
    	GatewayInfo.setDirectBank(
    		"{account_holder_name}", 
    		"{account_holder_city}", 
    		"{account_holder_country}",
    		"{account_holder_iban}",
    		"{account_holder_bic}")	
    ));

Create a Pay After Delivery, E-Invoicing or Klarna order

type: required
Specifies the payment flow for the checkout process. For Pay After Delivery and Klarna orders use the value "redirect". For E-Invoicing orders use the value "direct".

gateway: required
 
Specifies which payment gateway to use. For Pay After Delivery use "PAYAFTER". For Klarna use "KLARNA". For E-Invoicing use "EINVOICE".

order_id: required
The unique identifier from your system for the order.

currency: required
The currency you want the customer to pay with.

amount: required
The unique identifier from your system for the order.

description: required
A free text description which will be shown with the order in MultiSafepay Control. If the customers bank supports it this description will also be shown on the customers bank statement.

var1, var2, var3: optional
A free variable for custom data to be stored and persisted.

items: optional
Include an HTML formatted list of the items ordered. Used to customer how the order is displayed on payment pages and emails.

gateway_info: required

birthday: required for Klarna & Pay After Delivery, optional for E-Invoicing on request.
The birth date of the customer in the format dd-mm-yyyy. This is required for credit checks.

bank_account: required for Pay After Delivery
The formatted IBAN for the customer. This is required for credit checks.

phone: required
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: required
The email address where the system can send payment instructions to the customer.

gender: required for Klarna, optional for Pay After Delivery and E-Invoicing
The gender of the customer. Valid values are "male", "female".

referrer: optional
The address of the page (if any) which referred the user agent to the current page..

user_agent: optional
Contents of the User-Agent: header from the current request, if there is one. This is a string denoting the user agent being which is accessing the page. A typical example is: Mozilla/4.5 [en] (X11; U; Linux 2.2.9 i586)

payment_options: required

notification_url: required
The URL that MultiSafepay will send transaction status updates to when the status of a transaction changes.

redirect_url: required
Where we will direct a customer from our payment pages after a successful transaction.

cancel_url: required
Where we will direct a customer from our payment pages after a cancelled or unsuccessful transaction.

customer: required

locale: optional
Include to provide localized payment pages for the customer. Use the format AB_cd with ISO 639 language codes and ISO 3166 country codes.

ip_address: required
The IP address of the customer.

forwarded_ip: optional
The X-FORWARED-FOR header of the customer request when using a proxy.

first_name: required
The customer's first name.

last_name: required
The customer's last name.

house_number: required for Klarna, optional for Pay After Delivery and E-Invoicing
The house number of the customer's provided address

address1: required
Street name of customer's provided address.

address2: optional
Second line of customer's provided address.

house_number: required
Customer's provided house number.

zip_code: optional
Customer's provided zip / postal code.

city: required
Customer's provided city.

state: optional
Customer's provided state / province.

country: required
The two digit country code for the customer's provided country.

phone: optional
Customer's provided phone number.

email: optional
Customer's provided email address.

disable_send_email: optional
True if you will send your own bank transfer payment instructions to consumers and do not want MultiSafepay to do this.

shopping_cart: required

name: required
The name of the ordered product.

description: optional
More detailed description of the product.

unit_price: required
The (tax exclusive) price per unit of the ordered product.

quantity: required
The number of this particular item ordered.

merchant_item_id: required
Your unique identifier for this product.

tax_table_selector: required
The name of the provided tax table MultiSafepay should use when calculating tax on this product.

standalone: required
Set to default if this table should be used to calculate tax on shipping methods.

unit: optional
The units that the weight metric has been provided in.

value: optional
The number of units each of these items weighs.

checkout_options.tax_tables.default

shipping_taxed: required
Indicates whether or tax will be charged on the cost of shipping.

rate: required
The rate of tax to charge on items this rule is applied to in decimal format. e.g. 0.21

checkout_options.tax_tables.alternate

name: required
The name of this tax rule. Used in the tax_table_selector field on the items.

rate: required
The rate of tax to charge on items this rule is applied to in decimal format. e.g. 0.21

country: optional
The two digit country code that this tax rate applies too.

google_analytics: optional

Your Google Analytics Site Id. This will be injected into the payment pages so you can trigger custom events and track payment metrics.

Example
POST - /orders
{
    "type": null,
    "gateway": "PAYAFTER",
    "order_id": null,
    "currency": null,
    "amount": null,
    "description": null,
    "var1": null,
    "var2": null,
    "var3": null,
    "items": null,
    "gateway_info": {
        "birthday": null,
        "bank_account": null,
        "phone": null,
        "email": null,
		"gender": null,
        "referrer": null,
        "user_agent": null
    },
    "payment_options": {
        "notification_url": null,
        "redirect_url": null,
        "cancel_url": null,
        "close_window": true
    },
    "customer": {
        "locale": null,
        "ip_address": null,
        "forwarded_ip": null,
        "first_name": null,
        "last_name": null,
        "address1": null,
        "address2": null,
        "house_number": null,
        "zip_code": null,
        "city": null,
        "state": null,
        "country": null,
        "phone": null,
        "email": null,
        "disable_send_email": null,
 		"referrer": null,
        "user_agent": null
    },
    "shopping_cart": {
        "items": [
            {
                "name": null,
                "description": null,
                "unit_price": null,
                "quantity": null,
                "merchant_item_id": null,
                "tax_table_selector": null,
                "weight": {
                    "unit": null,
                    "value": null
                }
            }
        ]
    },
    "checkout_options": {
        "tax_tables": {
            "default": {
                "shipping_taxed": null,
                "rate": null
            },
            "alternate": [
                {
                    "standalone": false,
                    "name": "null",
                    "rules": [
                        {
                            "rate": null,
                            "country": null
                        }
                    ]
                }
            ]
        }
    },
    "google_analytics": {
        "account": "UA-XXXXXXXXX"
    }
}

	
$order = $msp->orders->post(array(
	"type" => "direct",
	"id" => "{orderId}",
	"currency" => "{currencyCode}",
	"amount" => {amount},
	"description" => "{description}",
	"gateway" => "PAYAFTER",
	"payment_options" => array(
		"notification_url" => "{notificationUrl}",
		"redirect_url" => "{successRedirectUrl}",
		"cancel_url" => "{cancelRedirectUrl}"
	),
	"customer" => array(
		"first_name" => "{firstName}",
		"last_name" => "{lastName}",
		"house_number" => "{number}",
		"address1" => "{street}",
		"zip_code" => "{postCode}",
		"city" => "{city}",
		"country" => "{countryCode}",
		"phone" => "{phoneNumber}",
		"email" => "{emailAddress}",
	),
	"gateway_info" => array(
		"birthday" => "{birthDate}",
		"bank_account" => "{iban}",
		"phone" => "{phoneNumber}",
		"gender" => "{gender}",
		"email" => "{email}",
		"referrer" => "{referrer}",
		"user_agent" => "{userAgent}",
	),
	"shopping_cart" => array(
		"items" => array(
			array(
				"name" => "{productName}",
				"unit_price" => "{price}",
				"quantity" => "{quantity}",
				"merchant_item_id" => "{productId}"
			)
		)
	)
));
client.CreateOrder(
	OrderRequest.CreateDirectPayAfterDeliveryOrder(
		{orderId}, "{description}", 
		{amount}, "{currencyCode}",
    	new PaymentOptions(
        	"{notificationUrl}",
        	"{successRedirectUrl}",
        	"{cancelRedirectUrl}"),
		GatewayInfo.PayAfterDelivery(
			new DateTime({birthYear}, {birthMonth}, {birthDay}), 
			"{iban}", "{phone}", "{email}", 
			"{referrer}", "{useragent}"
		),
		new ShoppingCart
		{
			Items = new[]
			{
			new ShoppingCartItem(
				"{productName", {price}, 
				{quantity}, "{currencyCode}")
			}
		},
		new Customer()
		{
			FirstName = "{firstName}",
			LastName = "{lastName}",
			HouseNumber = "{number}",
			Address1 = "{street}",
			City = "{city}",
			Country = "{countryCode}",
			PostCode = "{postCode}"
		}
	)
);
CheckoutOptions checkout_options	= new CheckoutOptions();
checkout_options.no_shipping_method = true;
List items 		= new ArrayList();
items.add(
	ShoppingCartItem.add(
		"{name}","{description}","{unit_price}",
		"{currency}","{quantity}","{merchant_item_id}",
		"{tax_table_selector}",
		Weight.set("{unit}", "{value}")
	));
		
MultiSafepayClient.createOrder(
	order.setDirectIdeal(
    	"{order_id}", 
    	"{description}", 
    	{amount}, 
    	"{currency}", 
    	new PaymentOptions("{notification_url}", "{cancel_url}", "{redirect_url}"),
    	GatewayInfo.setPayAfter("{birthday}","{bank_account}","{phone}","{email}"),
    	new ShoppingCart(items),
    	checkout_options
    ));

Create a Fast Checkout order

type: required
Specifies the payment flow for the checkout process. For Pay After Delivery orders use the value "checkout".

gateway: optional
Sets a predefined payment method

order_id: required
The unique identifier from your system for the order.

currency: required
The currency you want the customer to pay with.

amount: required
The unique identifier from your system for the order.

description: required
A free text description which will be shown with the order in MultiSafepay Control. If the customers bank supports it this description will also be shown on the customers bank statement.

var1, var2, var3: optional
A free variable for custom data to be stored and persisted.

items: optional
Include an HTML formatted list of the items ordered. Used to customer how the order is displayed on payment pages and emails.

payment_options: required

notification_url: required
The URL that MultiSafepay will send transaction status updates to when the status of a transaction changes.

redirect_url: required
Where we will direct a customer from our payment pages after a successful transaction.

cancel_url: required
Where we will direct a customer from our payment pages after a cancelled or unsuccessful transaction.

customer: optional

company: optional

Set to to true in order to force a customer to enter a company name during the checkout process.

locale: optional
Include to provide localized payment pages for the customer. Use the format AB_cd with ISO 639 language codes and ISO 3166 country codes.

ip_address: optional
The IP address of the customer.

forwarded_ip: optional
The X-FORWARED-FOR header of the customer request when using a proxy.

referrer: optional
The address of the page (if any) which referred the user agent to the current page..

user_agent: optional
Contents of the User-Agent: header from the current request, if there is one. This is a string denoting the user agent being which is accessing the page. A typical example is: Mozilla/4.5 [en] (X11; U; Linux 2.2.9 i586)

first_name: optional
The customer's first name.

last_name: optional
The customer's last name.

address1: optional
First line of customer's provided address.

address2: optional
Second line of customer's provided address.

house_number: optional
Customer's provided house number.

zip_code: optional
Customer's provided zip / postal code.

city: optional
Customer's provided city.

state: optional
Customer's provided state / province.

country: optional
Customer's provided country.

phone: optional
Customer's provided phone number.

email: optional
Customer's provided email address.

shopping_cart: required

name: required
The name of the ordered product.

description: optional
More detailed description of the product.

unit_price: required
The (tax exclusive) price per unit of the ordered product.

currency: required
The currency for the unit_price of this product. All currencies must be the same as the order currency.

quantity: required
The number of this particular item ordered.

merchant_item_id: required
Your unique identifier for this product.

tax_table_selector: required
The name of the provided tax table MultiSafepay should when calculating tax on this product.

shopping_cart.item.weight

unit: optional
The units that the weight metric has been provided in.

value: optional
The number of units each of these items weighs.

checkout_options 

no_shipping_method: optional

Set to true to skip the shipping address selection during the checkout process. Default value is false.

use_shipping_notification: optional

In some instances it is not possible to send shipping options with the order request. Set this option to true in order to trigger a request to your webshop to retrieve shipping options during customer checkout. Default value is false.

checkout_options.shipping_methods.flat_rate_shipping : required

name: required
The name of the shipping company.

price: required
The price charged to the customer for using this shipping method.

currency: required
The currency that this shipping method will be charged in.

allowed_areas: optional
A comma separated list of ISO 3166-1 country codes for which countries this shipping method is available. Countries not in this list will not support this shipping method.

excluded_areas: optional
A comma separated list of ISO 3166-1 country codes for which countries this shipping method is not available.

checkout_options.shipping_methods.pickup

name: required
The name of the pickup location.

price:required
The price charged to the customer for using this shipping method.

currency:required

The currency that this shipping method will be charged in.

checkout_options.tax_tables.default

shipping_taxed: required
Indicates whether or tax will be charged on the cost of shipping.

rate: required
The rate of tax to charge on items this rule is applied to in decimal format. e.g. 0.21

checkout_options.tax_tables.alternate

standalone: required
Set to default if this table should be used to calculate tax on shipping methods.

name: required
The name of this tax rule. Used in the tax_table_selector field on the items.

rate: required
The rate of tax to charge on items this rule is applied to in decimal format. e.g. 0.21

checkout_options.rouding_policy

mode: required
Select the rounding policy to use. Supported values are: UP, DOWN, CEILING, HALF_UP, HALF_DOWN, HALF_EVEN.

rule: required
States how to apply the rounding policy. Supported values are: PER_ITEM, PER_LINE, TOTAL.

custom_info.item

standard_type: optional
Choose from a predefined list of standard fields associated with user accounts. If this attribute is set all other attributes will be ignored. Supported values are: vatnumber, companyname, chamberofcommerce, driverslicense, passportnumber, birthday, sex, newsletter, comment, mobilephonenumber, salutation, phonenumber, acceptagreements.

name: required
The name of the custom field used to store and retrieve the data. Only accepts alphanumeric characters without whitespace.

type: required
The input type for the field. Supported values are: textbox, selectbox, checkbox, radiolist.

label: required
The label that will be displayed next to the input field.

save_value: optional
Save the value of this field so that it will be automatically populated next time the customer checks out. 

default: optional
Provide a default value for the field. 

custom_info.item.description

value: required
The value to display on the screen.

style: optional
Optional inline css style apply to the label. 

custom_info.item.area_restrictions

allowed_areas: optional
A comma separated list of ISO 3166-1 country codes for which countries this custom field will be displayed. If specified then the custom field is only displayed for users with billing addresses in these countries.

excluded_areas: optional
A comma separated list of ISO 3166-1 country codes for which countries this custom field will not be displayed. If specified then the custom field is only displayed for users with billing addresses outside these countries.

google_analytics: optional
Your Google Analytics Site Id. This will be injected into the payment pages so you can trigger custom events and track payment metrics.

Example
POST - /orders
{
    "type": "checkout",
    "gateway": null,
    "order_id": null,
    "currency": null,
    "amount": null,
    "description": null,
    "var1": null,
    "var2": null,
    "var3": null,
    "items": null,
    "manual": null,
    "payment_options": {
        "notification_url": null,
        "cancel_url": null,
        "redirect_url": null,
        "close_window": null
    },
    "plugin": {
        "shop": null,
        "plugin_version": null,
        "shop_version": null,
        "partner": null,
        "shop_root_url": null
    },
    "customer": {
        "locale": null,
        "ip_address": null,
        "forwarded_ip": null,
        "first_name": null,
        "last_name": null,
        "address1": null,
        "address2": null,
        "house_number": null,
        "zip_code": null,
        "city": null,
        "state": null,
        "country": null,
        "phone": null,
        "email": null,
        "referrer": null,
        "user_agent": null
    },
    "delivery": {
        "first_name": null,
        "last_name": null,
        "address1": null,
        "address2": null,
        "house_number": null,
        "zip_code": null,
        "city": null,
        "state": null,
        "country": null,
        "phone": null,
        "email": null
    },
    "gateway_info": {
        "birthday": null,
        "bank_account": null,
        "phone": null,
        "email": null,
        "referrer": null,
        "user_agent": null
    },
    "shopping_cart": {
        "items": [
            {
                "name": null,
                "description": null,
                "unit_price": null,
                "quantity": null,
                "merchant_item_id": null,
                "tax_table_selector": null,
                "weight": {
                    "unit": null,
                    "value": null
                }
            }
        ]
    },
    "checkout_options": {
        "rounding_policy": {
            "mode": null,
            "rule": null
        },
        "shipping_methods": {
            "flat_rate_shipping": [
                {
                    "name": null,
                    "price": null,
                    "allowed_areas": [
                        "NL",
                        "ES"
                    ]
                },
                {
                    "name": null,
                    "price": null,
                    "excluded_areas": [
                        "NL",
                        "FR",
                        "ES"
                    ]
                }
            ]
        },
        "tax_tables": {
            "default": {
                "shipping_taxed": null,
                "rate": null
            },
            "alternate": [
                {
                    "name": null,
                    "rules": [
                        {
                            "rate": null,
                            "country": null
                        }
                    ]
                }
            ]
        },
        "custom_fields": [
            {
                "name": null,
                "type": null,
                "label": null,
                "description_right": {
                    "value": [
                        {
                            "nl": null
                        },
                        {
                            "en": null
                        }
                    ]
                },
                "validation": {
                    "type": "regex",
                    "data": "^[1]$",
                    "error": [
                        {
                            "nl": null
                        },
                        {
                            "en": null
                        }
                    ]
                }
            },
            {
                "standard_type": "companyname"
            },
            {
                "standard_type": "passportnumber",
                "validation": {
                    "type": null,
                    "data": null,
                    "error": null
                }
            }
        ]
    },
    "google_analytics": {
        "account": "UA-XXXXXXXXX"
    }
}
	
$order = $msp->orders->post(array(
	"type" => "direct",
	"id" => "{orderId}",
	"currency" => "{currencyCode}",
	"amount" => {amount},
	"description" => "{description}",
	"gateway" => "checkout",
	"payment_options" => array(
		"notification_url" => "{notificationUrl}",
		"redirect_url" => "{successRedirectUrl}",
		"cancel_url" => "{cancelRedirectUrl}"
	),
	"customer" => array(
		"first_name" => "{firstName}",
		"last_name" => "{lastName}",
		"address1" => "{street}",
		"housenumber" => "{number}",
		"zip_code" => "{postCode}",
		"city" => "{city}",
		"country" => "{countryCode}",
		"phone" => "{phoneNumber}",
		"email" => "{emailAddress}",
	),
	"shopping_cart" => array(
		"items" => array(
			array(
				"name" => "{productName}",
				"unit_price" => "{price}",
				"quantity" => "{quantity}",
				"merchant_item_id" => "{productId}"
			)
		)
	),
	"shipping_methods": {
		"flat_rate_shipping": {
			"name" => "{methodName}",
			"price" => "{price}",
			"currency" => "{currency}"
		}
	}
));
client.CreateOrder(
	OrderRequest.CreateFastCheckoutOrder(
		{orderId}, "{description}", 
		{amount}, "{currencyCode}",
		new PaymentOptions(
			"{notificationUrl}",
			"{successRedirectUrl}",
			"{cancelRedirectUrl}"),
		new ShoppingCart
		{
			Items = new[]
			{
				new ShoppingCartItem(
					"{product}", {price}, 
					{quantity}, "{currencyCode}")
			}
		},
		new CheckoutOptions()
		{
			ShippingMethods = new ShippingMethods()
			{
				FlatRateShippingMethods = new[]
				{
					new ShippingMethod("{name}", {amount}, "{currencyCode}")
				}
			}
		}
	)
);
CheckoutOptions checkout_options	= new CheckoutOptions();
checkout_options.no_shipping_method = true;
    	
List items 		= new ArrayList();
items.add(
	ShoppingCartItem.add(
		"{name}","{description}","{unit_price}",
		"{currency}","{quantity}","{merchant_item_id}",
		"{tax_table_selector}",
		Weight.set("{unit}", "{value}")
	));
    	
MultiSafepayClient.createOrder(
	order.setFastCheckout(
    	"{order_id}", 
    	"{description}", 
    	{amount}, 
    	"{currency}", 
    	new PaymentOptions("{notification_url}", "{cancel_url}", "{redirect_url}"),
		new ShoppingCart(items),
		checkout_options
	));

Retrieve an order

order_id: required
The unique identifier of the order to be returned.

Example
GET - /orders/{order_id}
	
$msp->orders->get($endpoint = 'orders', {orderId}, $body=array(), $query_string = false);
client.GetOrder("{orderId}");
MultiSafepayClient.GetOrder("{order_id}");

Update shipping status

order_id: required
The unique identifier of the order which should be updated.

tracktrace_code: required
The track and trace code provided by the shipping company.

carrier: required
The name of the shipping company delivering the customer's order.

ship_date: required
The date that the order was shipped.

reason: optional
Add a short free text memo to the order when setting the shipping status.

Example
PATCH - /orders/{order_id}
{
	"tracktrace_code": null,  
	"carrier": null,
	"ship_date": null,
	"reason": null
}
	
$msp->orders->patch(array(
	"tracktrace_code" => "{tracetrace_code},
	"carrier" => "{carrier},
	"ship_date" => "{ship_date}, 
	"reason" => "{reason} 
"), $endpoint);
client.UpdateOrderShippedStatus(
	"{orderId}", "{trackTraceCode}", "{shippingCompany}", 
	new DateTime("{yearSent}, {monthSent}, {daySent}, "{memo}"
);
MultiSafepayClient.SetOrderShipping(
	"{order_id}", "{ship_date}", 
	"{carrier}", "{tracktrace_code}"
);

Set order invoice id

order_id: required
The unique identifier of the order which should be updated.

invoice_id: required
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.

Example
PATCH - /orders/{order_id}
{
	"invoice_id": null
}
	
$msp->orders->patch(array("invoice_id" => "{invoice_id}"), $endpoint);
client.SetOrderInvoiceNumber(
	"{orderId}", "{invoiceId}"
);
MultiSafepayClient.SetOrderInvoice("{order_id}","{invoice_id}");

Dynamic Template

Within a transaction request a template of the MultiSafepay payment page can be defined. This can be done by providing a template_id of a predefined template within the MultiSafepay account, or by providing a template object structure within the transaction request. When both are provided within the request, 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.

 

template_id: optional
The unique identifier of a predefined configured template.

template: optional
A template object structure.

 

Example
{  
   "type":"redirect",
   "order_id":"dynamic-template123",
   "gateway":"",
   "currency":"EUR",
   "amount":"1000",
   "description":"Test Order Dynamic Template",
   "payment_options":{  
      "notification_url":"",
      "redirect_url":"",
      "cancel_url":"",
      "template_id":"",
      "template":{  
         "version":"1.0",
         "settings":{  
            "hide_logo":""
         },
         "header":{  
            "logo":{  
               "image":"/assets/img/logo-msp.png"
            },
            "cover":{  
               "image":""
            },
            "background":"#ffffff",
            "text":"#333"
         },
         "body":{  
            "text":"#333",
            "background":"#fdfcfc",
            "link":{  
               "text":"#00acf1",
               "hover":{  
                  "text":"",
                  "border":""
               }
            }
         },
         "container":{  
            "text":"",
            "label":"#a4a3a3",
            "background":"#ffffff",
            "link":{  
               "text":""
            }
         },
         "cart":{  
            "text":"",
            "label":"#a4a3a3",
            "background":"#ffffff",
            "border":""
         },
         "payment_form":{  
            "text":"",
            "background":"#ffffff",
            "border":"",
            "inputs":{  
               "border":"#bdbbbb",
               "label":"#8b8b8b"
            }
         },
         "buttons":{  
            "payment_method":{  
               "background":"#ffffff",
               "text":"",
               "border":"#d7d7d7",
               "hover":{  
                  "background":"#f5f7f9",
                  "text":"",
                  "border":""
               },
               "active":{  
                  "background":"",
                  "text":"",
                  "border":""
               }
            },
            "secondary":{  
               "background":"#00acf1",
               "text":"#fff",
               "hover":{  
                  "background":"",
                  "text":""
               }
            },
            "primary":{  
               "background":"#ccc",
               "text":"",
               "hover":{  
                  "background":"",
                  "text":""
               }
            }
         }
      }
   },
   "customer":{  
      "locale":"en"
   }
}
	
{  
   "type":"redirect",
   "order_id":"dynamic-template123",
   "gateway":"",
   "currency":"EUR",
   "amount":"1000",
   "description":"Test Order Dynamic Template",
   "payment_options":{  
      "notification_url":"",
      "redirect_url":"",
      "cancel_url":"",
      "template_id":"",
      "template":{  
         "version":"1.0",
         "settings":{  
            "hide_logo":""
         },
         "header":{  
            "logo":{  
               "image":"/assets/img/logo-msp.png"
            },
            "cover":{  
               "image":""
            },
            "background":"#ffffff",
            "text":"#333"
         },
         "body":{  
            "text":"#333",
            "background":"#fdfcfc",
            "link":{  
               "text":"#00acf1",
               "hover":{  
                  "text":"",
                  "border":""
               }
            }
         },
         "container":{  
            "text":"",
            "label":"#a4a3a3",
            "background":"#ffffff",
            "link":{  
               "text":""
            }
         },
         "cart":{  
            "text":"",
            "label":"#a4a3a3",
            "background":"#ffffff",
            "border":""
         },
         "payment_form":{  
            "text":"",
            "background":"#ffffff",
            "border":"",
            "inputs":{  
               "border":"#bdbbbb",
               "label":"#8b8b8b"
            }
         },
         "buttons":{  
            "payment_method":{  
               "background":"#ffffff",
               "text":"",
               "border":"#d7d7d7",
               "hover":{  
                  "background":"#f5f7f9",
                  "text":"",
                  "border":""
               },
               "active":{  
                  "background":"",
                  "text":"",
                  "border":""
               }
            },
            "secondary":{  
               "background":"#00acf1",
               "text":"#fff",
               "hover":{  
                  "background":"",
                  "text":""
               }
            },
            "primary":{  
               "background":"#ccc",
               "text":"",
               "hover":{  
                  "background":"",
                  "text":""
               }
            }
         }
      }
   },
   "customer":{  
      "locale":"en"
   }
}
{  
   "type":"redirect",
   "order_id":"dynamic-template123",
   "gateway":"",
   "currency":"EUR",
   "amount":"1000",
   "description":"Test Order Dynamic Template",
   "payment_options":{  
      "notification_url":"",
      "redirect_url":"",
      "cancel_url":"",
      "template_id":"",
      "template":{  
         "version":"1.0",
         "settings":{  
            "hide_logo":""
         },
         "header":{  
            "logo":{  
               "image":"/assets/img/logo-msp.png"
            },
            "cover":{  
               "image":""
            },
            "background":"#ffffff",
            "text":"#333"
         },
         "body":{  
            "text":"#333",
            "background":"#fdfcfc",
            "link":{  
               "text":"#00acf1",
               "hover":{  
                  "text":"",
                  "border":""
               }
            }
         },
         "container":{  
            "text":"",
            "label":"#a4a3a3",
            "background":"#ffffff",
            "link":{  
               "text":""
            }
         },
         "cart":{  
            "text":"",
            "label":"#a4a3a3",
            "background":"#ffffff",
            "border":""
         },
         "payment_form":{  
            "text":"",
            "background":"#ffffff",
            "border":"",
            "inputs":{  
               "border":"#bdbbbb",
               "label":"#8b8b8b"
            }
         },
         "buttons":{  
            "payment_method":{  
               "background":"#ffffff",
               "text":"",
               "border":"#d7d7d7",
               "hover":{  
                  "background":"#f5f7f9",
                  "text":"",
                  "border":""
               },
               "active":{  
                  "background":"",
                  "text":"",
                  "border":""
               }
            },
            "secondary":{  
               "background":"#00acf1",
               "text":"#fff",
               "hover":{  
                  "background":"",
                  "text":""
               }
            },
            "primary":{  
               "background":"#ccc",
               "text":"",
               "hover":{  
                  "background":"",
                  "text":""
               }
            }
         }
      }
   },
   "customer":{  
      "locale":"en"
   }
}
{  
   "type":"redirect",
   "order_id":"dynamic-template123",
   "gateway":"",
   "currency":"EUR",
   "amount":"1000",
   "description":"Test Order Dynamic Template",
   "payment_options":{  
      "notification_url":"",
      "redirect_url":"",
      "cancel_url":"",
      "template_id":"",
      "template":{  
         "version":"1.0",
         "settings":{  
            "hide_logo":""
         },
         "header":{  
            "logo":{  
               "image":"/assets/img/logo-msp.png"
            },
            "cover":{  
               "image":""
            },
            "background":"#ffffff",
            "text":"#333"
         },
         "body":{  
            "text":"#333",
            "background":"#fdfcfc",
            "link":{  
               "text":"#00acf1",
               "hover":{  
                  "text":"",
                  "border":""
               }
            }
         },
         "container":{  
            "text":"",
            "label":"#a4a3a3",
            "background":"#ffffff",
            "link":{  
               "text":""
            }
         },
         "cart":{  
            "text":"",
            "label":"#a4a3a3",
            "background":"#ffffff",
            "border":""
         },
         "payment_form":{  
            "text":"",
            "background":"#ffffff",
            "border":"",
            "inputs":{  
               "border":"#bdbbbb",
               "label":"#8b8b8b"
            }
         },
         "buttons":{  
            "payment_method":{  
               "background":"#ffffff",
               "text":"",
               "border":"#d7d7d7",
               "hover":{  
                  "background":"#f5f7f9",
                  "text":"",
                  "border":""
               },
               "active":{  
                  "background":"",
                  "text":"",
                  "border":""
               }
            },
            "secondary":{  
               "background":"#00acf1",
               "text":"#fff",
               "hover":{  
                  "background":"",
                  "text":""
               }
            },
            "primary":{  
               "background":"#ccc",
               "text":"",
               "hover":{  
                  "background":"",
                  "text":""
               }
            }
         }
      }
   },
   "customer":{  
      "locale":"en"
   }
}

 

Create a refund

id: required
The unique identifier of the order which the payment link is to be retrieved for.

type: required
Specifies the type of transaction to create. The only supported value at this time is refund.

amount: required
The amount (in cents) to be refunded.

currency: required
The currency to process the refund in. This must be the same as the original transaction.

description: required
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.

Example
POST - /orders/{id}/refunds
{
	"type": "refund",
	"amount": null,
	"currency": null,
	"description": null
}
	
$msp->orders->post(array(
	"type" => "refund",
	"amount" => "{amount}",
	"currency" => "{currencyCode}",
	"description" => "{description}",
), $endpoint);
client.CreateRefund(
	"{orderId}", {refundAmount}, "{currencyCode}", "{memo}"
);
MultiSafepayClient.SetOrderRefund("{order_id}",{amount},"{currency}","{description}");

 

Transaction statuses

Transactions can have the following statuses:

 
Status 
 
 
Description 
 
InitializedA payment link has been generated, but no payment has been received yet.
DeclinedRejected by the credit card company.
CanceledCanceled by the merchant (only applies to the status Initialised or Uncleared).
CompletedPayment has been successfully completed.
ExpiredDepending on the payment method unfinished transactions automatically expire after a predefined period.
UnclearedWaiting for manual permission of the merchant to approve/disapprove the payment. 
RefundedPayment has been refunded to the customer.
Partial_RefundedThe payment has been partially refunded to the customer.
ReservedPayout/refund has been temporary put on reserved, a temporary status, till the e-wallet has
been checked on sufficient balance.
VoidFailed payment. 
ChargedbackForced reversal of funds initiated by consumer’s issuing bank. Only applicable to direct debit and credit card payments.