Step-by-Step

 

Before you begin

Before you begin you will need to create a merchant account by completing steps 1 and 2 from our Getting Started guide. Make note of the API Key for your new website as you will need it when authenticating using the Payment API.

Next download one of our Code Wrappers for your preferred language.

Redirect vs Direct Payments

A redirect payment is the standard payment process. During a redirect payment the consumer is redirected to MultiSafepay's secure Hosted Payment Pages to enter their payment details and is suitable for most scenarios. If you prefer greater control over your checkout process you should use direct payments. During a direct payment the consumer does not need to visit MultiSafepay Hosted Payment Pages. Instead your website collects the requirement payment details and the consumer is redirect immediately to their chosen payment provider. Direct payments are only available for iDEAL, Direct Debit and Bank Transfers.

Standard Payment Example

1. Select Payment Method (optional)

If you would like your customer to select their payment method on your website, rather than on the MultiSafepay Hosted Payment Page, you should first retrieve a list of the supported payment methods.

Example
GET - /gateways
	
$gateways = $msp->gateways->get();
client.GetGateways();
MultiSafepayClient.GetGateways();

2. Start the Payment

To start a payment you will create an order with MultiSafepay. This call returns a payment URL which you will redirect the consumer to. You can skip the payment selection screen and direct the consumer to a certain payment method directly by specifying the GatewayId property on the 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.

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.

Example
POST - /orders
{
    "type": "redirect",
    "order_id": null,
    "description": null,
    "currency": null,
    "amount": null,
    "payment_options": {
        "notification_url": null,
        "redirect_url": null,
        "cancel_url": null
    }
}
	
$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}")
    ));

3. Update local order status on notification

MultiSafepay will send your website a notification when the status of an order changes. You will then retrieve the latest order information from MultiSafepay to continue processing or cancel the order. The URL that this notification will be sent to can be set when you initialize an order or from within MultiSafepay Control. The MultiSafepay notification is sent using an HTTP GET and expects the strong OK in the response if the notification was handled successfully.

Example
GET - /orders/{order_id}
	
$transactionid = $_GET['transactionid']; 
$msp->orders->get($endpoint = 'transactions', $transactionid, $body=array(), $query_string = false);

$yourStatus = "initialized"; // Get the order status from your system
 
if($yourStatus  != $order->status) { // Update your status if different
	switch ($order->status) {
		case "initialized": // waiting
			break;
		case "completed":   // payment complete
			break;
		case "uncleared":   // waiting (credit cards or direct debit)
			break;
		case "void":        // canceled
			break;
		case "declined":    // declined
			break;
		case "refunded":    // refunded
			break;
		case "expired":     // expired
			break;
		default:
	}
}
var transactionId = HttpContext.Request.QueryString["transactionid"];
var order = client.GetOrder(transactionId);

var yourStatus = "initialized"; // Get the order status from your system
 
if(yourStatus  != order.Status) { // Update your status if different
	switch (order.Status) {
	    case "initialized": // waiting
			break;
	    case "completed":   // payment complete
			break;
	    case "uncleared":   // waiting (credit cards or direct debit)
			break;
	    case "void":        // canceled
			break;
	    case "declined":    // declined
			break;
	    case "refunded":    // refunded
			break;
	    case "expired":     // expired
			break;
	    default:
	}
}
JsonObject order = MultiSafepayClient.GetOrder("{order_id}");

String yourStatus = "initialized"; // Get the order status from your system
 
if(yourStatus  != order.get("status")) { // Update your status if different
	switch (order.Status) {
	    case "initialized": // waiting
			break;
	    case "completed":   // payment complete
			break;
	    case "uncleared":   // waiting (credit cards or direct debit)
			break;
	    case "void":        // canceled
			break;
	    case "declined":    // declined
			break;
	    case "refunded":    // refunded
			break;
	    case "expired":     // expired
			break;
	    default:
	}
}

Direct iDEAL Payment Example

1. Select Payment Method (required)

First retrieve the list of active payment methods on your website and present to your consumer.

For iDEAL you will also need to present the consumer with a list of issuing banks so they can select the bank they will use to process the payment.

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

2. Start the Payment

Provided the consumer has chosen a payment method that supports the direct payment process you can send all the required payment details to MultiSafepay for processing.

type: required
Specifies the payment flow for the checkout process. For direct payments use the value "direct".

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_info: required

issuer_id: required
The name of the issuer / bank to direct the customer to in order to finish the transaction. Allowed values can be retrieved from retrieve issuers for gateway.

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.

Example
POST - /orders
{
    "type": "direct",
    "order_id": null,
    "description": null,
    "currency": null,
    "amount": null,
    "gateway_info": {
        "issuer_id": null
    },
    "payment_options": {
        "notification_url": null,
        "redirect_url": null,
        "cancel_url": null
    }
}
	
$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.setDirectIdeal(
		"{orderId}", 
		"{description}", 
		{amount}, "{currencyCode}",
		new PaymentOptions(
			"{notificationUrl}", 
			"{successRedirectUrl}", 
			"{cancelledRedirectUrl}"
		),
		GatewayInfo.setDirectIdeal("{issuerId}")
	)
);

3. Update local order status on notification

MultiSafepay will send your website a notification when the status of an order changes. You will then retrieve the latest order information from MultiSafepay to continue processing or cancel the order. The URL that this notification will be sent to can be set when you initialize an order or from within MultiSafepay Control. The MultiSafepay notification is sent using an HTTP GET and expects the string OK in the response if the notification was handled was handled successfully.

Example
GET - /orders/{order_id}
	
$transactionid = $_GET['transactionid']; 
$msp->orders->get($endpoint = 'transactions', $transactionid, $body=array(), $query_string = false);

$yourStatus = "initialized"; // Get the order status from your system
 
if($yourStatus  != $order->status) { // Update your status if different
	switch ($order->status) {
		case "initialized": // waiting
			break;
		case "completed":   // payment complete
			break;
		case "uncleared":   // waiting (credit cards or direct debit)
			break;
		case "void":        // canceled
			break;
		case "declined":    // declined
			break;
		case "refunded":    // refunded
			break;
		case "expired":     // expired
			break;
		default:
	}
}
var transactionId = HttpContext.Request.QueryString["transactionid"];
var order = client.GetOrder(transactionId);

var yourStatus = "initialized"; // Get the order status from your system
 
if(yourStatus  != order.Status) { // Update your status if different
	switch (order.Status) {
	    case "initialized": // waiting
			break;
	    case "completed":   // payment complete
			break;
	    case "uncleared":   // waiting (credit cards or direct debit)
			break;
	    case "void":        // canceled
			break;
	    case "declined":    // declined
			break;
	    case "refunded":    // refunded
			break;
	    case "expired":     // expired
			break;
	    default:
	}
}
JsonObject order = MultiSafepayClient.GetOrder("{order_id}");

String yourStatus = "initialized"; // Get the order status from your system
 
if(yourStatus  != order.get("status")) { // Update your status if different
	switch (order.Status) {
	    case "initialized": // waiting
			break;
	    case "completed":   // payment complete
			break;
	    case "uncleared":   // waiting (credit cards or direct debit)
			break;
	    case "void":        // canceled
			break;
	    case "declined":    // declined
			break;
	    case "refunded":    // refunded
			break;
	    case "expired":     // expired
			break;
	    default:
	}
}