1. Home
  2. API Reference

API Reference

Welcome to the MultiSafepay API Reference (JSON gateway).

The left column contains a table of contents.

The middle column provides detailed information about each topic and how to make an API request, including parameters and data types.

The right column shows example JSON requests and responses.

Using our API

You can use our API to make requests, for example, to:

Advanced requests include making split payments and recurring payments.

You can also use our API to build a custom integration. You can test your integration in the TEST environment. See also our Postman collection of sample requests.

For any questions, email the Integration Team at [email protected]

TEST API

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

LIVE API

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

Environments

MultiSafepay provides a:

Use the test environment when developing and testing a new integration with our API. No real transactions are processed.

To start processing real transactions, just address the live API and update your API key.

Test API

curl -X POST "https://testapi.multisafepay.com/v1/json/" \
--header "api_key: <your-test-API-key>"

Live API

curl -X POST "https://api.multisafepay.com/v1/json/" \
--header "api_key: <your-API-key>"

Authentication

All requests to the MultiSafepay API require authentication.

Include your website API key as an HTTP header in your request: api_key

Note: Always keep your API keys secure. Publicly exposing your credentials can compromise your account.

GET - /auth/api_token/

JSON response

{
  "success": true,
  "data": {
    "api_token": "pub.v2.xxxxxxxx"
  }
}

Generating API tokens

API tokens are used to encrypt sensitive payment details from a customer’s device.

Generate a new token for every order, except POST /orders requests initiated from your server.

GET - /gateways?locale=es

Specifying the response language

The default language for displaying gateway information and other messages in responses is English.

To specify the language of a response, add the ISO 639-1 language code as a localization parameter to the query string of the request.

Gateways

Payment gateways facilitate transactions by transfering information between your backend, MultiSafepay, and the payment method.

Available payment methods in your MultiSafepay account are returned as gateways.

GET - /gateways

JSON response

{
    "success": true,
    "data": [
        {
            "id": null,
            "description": null
        }
    ]
}

Retrieve all gateways

Parameters

include | string | optional

Additional payment methods you want to specify.
Format: Comma delimited.

Options: coupons

To include all gift cards your website supports in the response, add the include=coupons value to your GET request. Otherwise, only one gift card is returned in the response.

GET - /gateways/{id}

JSON response

{
    "success": true,
    "data": {
      "id": null,
      "description": null
    }
}

Retrieve a specific gateway

Parameters

id | string | required

The unique identifier of the requested gateway.

country | string | optional

The customer’s country code.
Format: ISO 3166-1 alpha-2, e.g. NL.

currency | string | optional

The currency you want the customer to pay with.
Format: ISO-4217 currency codes.

amount | integer | optional

The amount (in cents) for the customer to pay.

GET - /issuers{gateway}

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": "1099",
      "description": "Revolut"
    },
    {
      "code": "4371",
      "description": "Bunq"
    },
    {
      "code": "1235",
      "description": "Handelsbanken"
    }
  ]
}

Retrieve gateway issuers

Parameters

code | string

The unique identifier of the payment gateway you want to retrieve a list of issuers for.
Supported identifiers: iDEAL

Possible issuers for direct iDEAL transactions:

IssuerID Bank
0031 ABN AMRO
0761 ASN Bank
4371 bunq
1235 Handelsbanken
0721 ING
0801 Knab
0021 Rabobank
0771 Regio Bank
1099 Revolut
0751 SNS Bank
0511 Triodos Bank
0161 Van Lanschot Bankiers

Orders

To process a transaction, you must create an order. There are two main types of orders:

  • Redirect: The customer is redirected to a MultiSafepay payment page (Connect) to complete payment.
  • Direct: The transaction is processed directly.

For more information, see Difference between direct and redirect.

Note: All fields must be completed correctly.

You can also create a:

  • Checkout order, which creates a “Fast Checkout Order”
  • Payment link in your MultiSafepay account

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": true
    },
    "customer": {
        "locale": "nl_NL",
        "ip_address": "123.123.123.123",
        "first_name": "Simon",
        "last_name": "Smit",
        "company_name": "Test Company Name",
        "address1": "Kraanspoor",
        "house_number": "39C",
        "zip_code": "1033SC",
        "city": "Amsterdam",
        "country": "NL",
        "phone": "0208500500",
        "email": "[email protected]",
        "referrer": "https://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"
    },
    "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

This is the default type of order.

Parameters

type | string | required

The payment flow for the checkout process.
Options: redirect, direct, checkout, paymentlink.

gateway | string | required

The unique gateway ID to direct the customer straight to the payment method.
To retrieve gateway IDs, see Gateways.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

google_analytics | object | optional

Your Google Analytics site ID, which is injected into the payment page so you can trigger custom events and track payment metrics.
For more information, see Google Analytics tracking via the API.

account | string | optional

The Google Analytics Tracking-ID.
See your Google Analytics dashboard.

customer | object | required

See customer (object).

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": 123456789
    "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": "Simon",
      "last_name": "Smit",
      "company_name": null,
      "address1": "Kraanspoor",
      "address2": "",
      "house_number": "39C",
      "zip_code": "1033SC",
      "city": "Amsterdam",
      "state": "NH",
      "country": "NL",
      "country_name": "The Netherlands",
      "phone1": "0208500500",
      "phone2": "00310000001",
      "email": "[email protected]"
    },
    "payment_details": {
      "recurring_id": null,
      "type": "IDEAL",
      "account_id": null,
      "account_holder_name": null,
      "external_transaction_id": "0050003729272772",
      "account_iban": "*** 1234",
      "isser_id": "0021"
    },
    "costs": [
      {
        "transaction_id": 123456789
        "description": "iDEAL Transactions",
        "type": "SYSTEM",
        "amount": 
      }
    ],
    "payment_url": "https://betalen.rabobank.nl/ideal-betaling/landingpage?random=44b2dcf080f29f6f52d05802fd76e31285ac564dc974319f0109e1d978234770&trxid=0050003729272772"
  }
}

Create a direct order

Supported payment methods:
ALIPAY, BANKTRANS, BELFIUS, CBC, CREDITCARD, DIRDEB, DIRECTBANK, EINVOICE, IDEAL, ING, KBC, KLARNA, PAYAFTER, PAYPAL

For additional required information, see the relevant payment method.

Parameters

type | string | required

The payment flow for the checkout process.
Options: direct.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

gateway | string | required

The unique gateway ID to direct the customer straight to the payment method.
To retrieve gateway IDs, see Gateways.

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

gateway_info | object

Contains:

issuer_id | string | required

The unique identifier of the gateway issuer.
To retrieve issuer IDs, see Retrieve gateway issuers.

payment_options | object | required

See payment_options (object).

{
	"days_active": 30,
	"seconds_active": 60,
	"description": "Test order description",
}

To set the lifetime of payment links, use the days_active and seconds_active parameters.

  • If seconds_active is set and larger than 0, then the seconds_active value determines the link lifetime.
  • If days_active is set, then the days_active value is used.
  • If neither parameter is set, the default is 30 days.
  • If both parameters are set, then the seconds_active value is used if larger than 0.

Parameters

days_active | string

The number of days to make the payment link active for.
Default: 30 days.

seconds_active | string

The number of seconds to make the payment link active for.
Default: 30 days.

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

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

Apply dynamic template

To apply a template to the MultiSafepay payment page, include in the transaction request:

  • The template_id of a template within your MultiSafepay account, or
  • A template object structure.

If you provide both, the template object is primary.

Template object structures

The template object structure must include full JSON CSS parameters. If you only send partial CSS settings, the parameter you send overrides the default MultiSafepay template.

When sending images in the template structure for the logo and header, you must use HTTPS, otherwise they will be ignored.

Parameters

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

gateway | string | required

The unique gateway ID to direct the customer straight to the payment method.
To retrieve gateway IDs, see Gateways.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

template | object | optional

A template object structure.
The template structure overrides the template_id.

Contains:

See settings (object).

template_id | string | optional

The identifier of a saved template from your MultiSafepay account. The template structure overrides the template_id.

PATCH - /orders

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

JSON response

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

Cancel a transaction

Cancel a pretransaction and/or a transaction based on the sessionid.

Parameters

status | string | required

The status of the order.
Fixed value: cancelled.

exclude_order | integer | required

Sets the outcome of the cancellation.
To cancel the pretransaction, set to 1.
To cancel both the pretransaction and the transaction, set to 0.
Note: Setting to 0 only works if the transaction status is Initialized. Transactions with Reserved status cannot be cancelled.

POST - /orders/{order_id}/files

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

JSON response

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

Challenge chargebacks

MultiSafepay can challenge chargebacks on your behalf. To do so, we need documented proof of the order.

You can upload the files or documents via a POST /order/{order_id}/files request.

Parameters

type | string | required

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

base64 | string | required

Binary Base 64 encoded.
Format: PDF, JPEG, PNG.

description | integer | required

Description of or comments on the submitted file.

name | string | required

Name of the submitted file.

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": 123456789
    "refund_id": 3326969
  }
}

Process a refund

Process a full or partial refund for an order.

Parameters

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

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

amount | integer | required

The amount (in cents) to be refunded.

Note: A 0 amount triggers a full refund. Use when the current balance of the transaction is unknown.

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

POST - /orders

{
   "type":"redirect",
   "gateway":"CREDITCARD",
   "order_id":"my-order-id-1",
   "currency":"EUR",
   "recurring_model":"unscheduled",
   "recurring_id":"hC6HdH7_5Tg",
   "recurring_flow":"token",
   "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":"en_NL",
      "ip_address":"85.149.25.654",
      "forwarded_ip":"",
      "first_name":"null",
      "last_name":"null",
      "address1":"Kraanspoor",
      "house_number":"39",
      "zip_code":"1033 SC",
      "city":"Amsterdam",
      "state":"",
      "country":"NL",
      "birthday":"07061993",
      "gender":"male",
      "phone":"0612345678",
      "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/82v6HsoQhaR823uIZ7hexDMwQyielzLrdox/?lang=nl_NL"
   }
}

Recurring payments

You can initiate recurring payments using tokenization for the following payment methods:

  • VISA
  • MasterCard
  • Maestro
  • Bancontact
  • American Express
  • iDEAL
  • SOFORT
  • Direct debit

Customers can make the initial payment using iDEAL, Bancontact, or SOFORT, followed by recurring payments using SEPA Direct Debit.

To process recurring payments:

  1. Submit a standard transaction request with recurring payments enabled.
  2. Request the token by retreiving the order.
  3. Make recurring payment requests as required.

Parameters

type | string | required

The payment flow for the checkout process.
Options: direct.

gateway | string | required

The payment method used for the checkout process.
Options: AMEX, DIRDEB, MASTERCARD, VISA.
Use DIRDEB when the initial payment was made using iDEAL, SOFORT, or SEPA Direct Debit.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

recurring_id | integer | required

The unique identifier for the recurring payment.

recurring_flow | string | required

The tokenization method used to create the recurring payment.
Options: token

recurring_model | string | required

The recurring model.
Options: unscheduled, subscription, cardonfile.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

notification_method | string

Sends push notification.
Options: POST, GET. Default: GET.

customer | object | required

See customer (object).

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

Refund post-payment orders that include a shopping_cart object.

  1. Make a GET /orders/{id} request to retrieve the items in the shopping cart.

  2. Add or remove items in the POST /orders/{id}/refunds request, depending on the type of post-payment method:

    • For Klarna, add a “copy” of the item to refund with a negative unit_price.
    • For all other post-payment methods, set a negative quantity.  

  3. Make sure that all data in the items matches the original transaction (except for the quantity or unit_price).

In the example, two out of three geometric candle holders were refunded. The exact same merchant_item_id, tax_table_selector and unit_price were provided.

Parameter

checkout_data | object | required

Contains the original shopping_cart object and copied items to be refunded.

GET - /orders/{order_id}

JSON response

{
  "success": true,
  "data": {
    "transaction_id": 123456789
    "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": "Simon",
      "last_name": "Smit",
      "address1": "Kraanspoor",
      "address2": "",
      "house_number": "39C",
      "zip_code": "1033SC",
      "city": "Amsterdam",
      "state": "NH",
      "country": "NL",
      "country_name": "The Netherlands",
      "phone1": "0208500500",
      "phone2": "00310000001",
      "email": "[email protected]"
    },
    "payment_details": {
      "recurring_id": 133761993_gTp2,
      "type": "VISA",
      "account_id": null,
      "account_holder_name": "Testperson-nl Approved",
      "external_transaction_id": 906015000050,
      "last4": "1234",
      "card_expiry_date": 1904
    },
    "costs": [
      {
        "transaction_id": 123456789
        "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": 123456789
      }
    ],
    "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

Retrieve the status of and information about a specific order. The structure may differ depending on the order type or method.

Parameters

order_id | integer / string | required

The unique identifier of the requested order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

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

Send Second chance emails

If the customer didn’t complete the payment, you can email a reminder containing a payment link.

For more information and requirements, see Second Chance.

You can enable/disable Second Chance emails per transaction request. The system uses the following rules:

(*) provided that the conditions above are fulfilled.

Parameters

second_chance | object | required

Sends a reminder email to the customer containing a payment link.

Contains:

send_email | boolean | required

Options:

  • true, sends reminder emails.
  • false or left empty, doesn’t send reminder emails.

Suppressing Second Chance emails after cancellation

When a customer plaes an order, goes to the checkout page, doesn’t complete payment, but later returns and tries again, some webshops create a second order. If Second Chance emails are enabled, the customer still receives emails for the first order, even after they complete payment for the second order.

Cancelling the first order doesn’t suppress Second Chance emails.

To suppress Second Chance emails, send a PATCH /orders request containing the following parameters:

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

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

Split the amount of a transaction between multiple MultiSafepay accounts, based on a percentage, a fixed amount, or a combination of the two.

For more information, see Split payments.

Parameters

type | string | required

The payment flow for the checkout process.
Options: direct, redirect, paymentlink.

gateway | string | required

The unique gateway ID to direct the customer straight to the payment method.
To retrieve gateway IDs, see Gateways.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

split_payments | object | required

Contains:

split_payments.merchant | integer

The account ID of the affiliated MultiSafepay account.

split_payments.percentage | float

Specify a percentage of the amount to split.

split_payments.fixed | integer

Specify the amount to split in cents.

split_payments.description | string

The description of the split payment.

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 details of an order.

Parameters

id | string | required

The unique identifier of the order you want to update.

status | string | required

The new status of the order.
Options: cancelled, shipped.

tracktrace_code | string | optional

The track and trace code provided by the shipping company.

carrier | string | optional

The name of the shipping company delivering the customer’s order.

ship_date | string | optional

The date that the order was shipped.

reason | string | optional

Add a short, free text memo for the order when setting the shipping status.

invoice_id | string | optional

Add your invoice ID to an existing order.
The ID appears on reports generated from your MultiSafepay account.

invoice_url | string | optional

The invoice URL linking to the invoice_id.

po_number | string | optional

The shipping company’s purchase order number.

{
    "checkout_options": {
        "validate_cart": true
    }
}

Validate shopping cart

Applies to non-post payment methods.

Parameters

checkout_options.validate_cart | boolean | required

If set to true, the value of amount is compared with the calculated total value of the shopping cart.

Returned as order_total.

If the values match, the request is submitted.

If the values don’t match, the request is not submitted and error_code 1027 is returned.

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

See also Payment methods – AfterPay.

AfterPay - direct

Parameters

type | string | required

The payment flow for the checkout process.
Options: redirect, direct.

gateway | string | required

The unique gateway identifier that directs the customer straight to the payment method.
Fixed value: AFTERPAY.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer, otherwise it is string.
Format: Maximum 35 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

Text displayed with the order in your MultiSafepay account, and on the customer’s bank statement (if supported by the bank).
Max. 200 characters.
HTML formatting is not supported. To add descriptions in HTML format, use the items or shopping_cart objects instead.

manual | string | required

Fixed value: false.

gateway_info | object | required

The customer data (issuer_id) required for conducting credit checks.

Contains:

birthday | object | required

The customer’s date of birth.
In the Netherlands and Belgium, this is required for credit checks.
Format: yyyy-mm-dd.

gender | string | required

The customer’s personal title.
Options: mr, mrs, miss.

phone | string | required

The customer’s phone number.
Required for credit checks and to contact the customer in case of non-payment.

email | string | required

The email address for sending payment instructions to the customer.

payment_options | object | required

See payment_options (object).

shopping_cart | object

See shopping_cart.items (object).

customer | object | required

See customer (object).

delivery | object

See delivery (object).

items | object

See items (object).

checkout_options | object

The definitions for the VAT class.

AfterPay - redirect

Parameters

type | string | required

The payment flow for the checkout process.
Options: redirect, direct.

gateway | string | required

The unique gateway ID that immediately directs the customer to the payment method.
Fixed value: AFTERPAY.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer, otherwise it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

delivery | object

See delivery (object).

shopping_cart | object

See shopping_cart.items (object).

items | object

See items (object).

checkout_options | object

The definitions for the VAT class.

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

See also Payment methods – in3.

in3 - direct

Parameters

type | string | required

The payment flow for the checkout process.
Options: redirect, direct.

gateway | string | required

The unique gateway identifier to direct the customer straight to the payment method.
To retrieve gateway IDs, see Gateways.
Options: IN3.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

manual | string | required

Fixed value: false.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

delivery | object

See delivery (object).

gateway_info | object

The customer data (issuer_id) required for conducting credit checks.

Contains:

birthday | object

The customer’s date of birth.
Required for credit checks in: DE, NL, DK, BE, AT. Optional: CH, NO, FI, SE. Format: yyyy-mm-dd.

gender | string

The customer’s personal title.
Options: mr, mrs, miss.

phone | string

The customer’s phone number.
Required for credit checks and to contact the customer in case of non-payment.

shopping_cart | object

See shopping_cart.items (object).

items | object

See items (object).

checkout_options | object

The definitions for the VAT class.

in3 - redirect

Parameters

type | string | required

The payment flow for the checkout process.
Options: redirect, direct.

gateway | string | required

The unique gateway identifier to direct the customer straight to the payment method.
Fixed value: IN3.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

delivery | object

See delivery (object).

shopping_cart | object

See shopping_cart.items (object).

items | object

See items (object).

checkout_options | object

The definitions for the VAT class.

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": true
    },
    "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": true
    },
    "customer": {
        "locale": "cn_CN",
        "ip_address": "123.123.123.123",
        "forwarded_ip": "",
        "first_name": "Simon",
        "last_name": "Smit",
        "address1": "Kraanspoor",
        "house_number": "39C",
        "zip_code": "1033SC",
        "city": "Amsterdam",
        "country": "NL",
        "phone": "0208500500",
        "email": "[email protected]",
        "referrer": "https://example.com",
        "user_agent": "Mozilla/5.0 (Windows NT 6.3; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/38.0.2125.111 Safari/537.36"
    }
}

JSON response

{
    "success": true,
    "data": {
        "transaction_id": 123456789
        "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": "Simon",
            "last_name": "Smit",
            "address1": "Kraanspoor",
            "house_number": "39C",
            "city": "Amsterdam",
            "country": "NL",
            "country_name": "The Netherlands",
            "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": "",
            "transaction_id": 123456789
            "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

See also Payment methods – Alipay.

Alipay - redirect

Parameters

type | string | required

The payment flow for the checkout process.
Options: redirect, direct, paymentlink.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

gateway | string | required

The unique gateway identifier to direct the customer straight to the payment method.
Fixed value: ALIPAY.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

Alipay - direct

Parameters

type | string | required

The payment flow for the checkout process.
Options: redirect, direct, paymentlink.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

gateway | string | required

The unique gateway identifier to direct the customer straight to the payment method.
Fixed value: ALIPAY.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

manual | string | required

Fixed value: false.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

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": true
  },
  "customer": {
    "locale": "nl_NL",
    "ip_address": "123.123.123.123"
  }
}

JSON response

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

American Express

Parameters

type | string | required

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

gateway | string | required

The gateway identifier.
Fixed value: AMEX.

Note: We also offer a generic CREDITCARD gateway. This can save space in mobile checkouts, but customers can’t immediately see which credit cards are supported. When the customer enters the first digits of their card number, the relevant credit card logo appears automatically.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

Detect Apple Pay on the customer’s 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);
    }

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

JSON Response

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

POST - /orders

{
  "type": "direct",
  "order_id": "my-order-id-1",
  "gateway": "APPLEPAY",
  "currency": "EUR",
  "amount": 1495,
  "description": "Order Description",
  "payment_options": {
      "notification_url": "http://www.example.com/client/notification?type=notification",
  },
  "gateway_info": {
    "payment_token": "{\"paymentData\":{\"data\":\"string\"},\"transactionIdentifier\":\"string\",\"paymentMethod\":{\"network\":\"string\",\"displayName\":\"string\"}}"
  }
}

JSON response

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

Apple Pay

Detecting Apple Pay on the customer’s device

To avoid an error if the customer’s device doesn’t support Apple Pay, we recommend running this piece of JavaScript to detect Apple Pay on the device.

Note: The code still displays Apple Pay as a payment method on a non-supported device. We recommend extending the script as required to hide Apple Pay.

Apple Pay - redirect

Parameters

type | string | required

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

gateway | string | required

The unique gateway identifier to direct the customer straight to the payment method.
Fixed value: APPLEPAY.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer, otherwise it is string.
Format: Maximum 35 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

manual | string | required

Fixed value: false.

payment_options | object | required

See payment_options (object).

Apple Pay - direct

Creates an Apple Pay direct order.

With direct integration, the  Pay button appears in your checkout page. Customers complete payment without being redirected to a payment page. Integrating Apple Pay direct payments requires a client-side integration with the Apple Pay JS API.

For a detailed integration manual, see Apple Pay direct integration

Parameters

type | string

Specifies the payment flow for the checkout process. For the Apple Pay direct integration, use direct.

gateway | string

For Apple Pay payments, use APPLEPAY.

order_id | integer / string

Your unique identifier for the order. Maximum number of characters: 35.

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 your MultiSafepay account. Max 200 characters.

payment_options.notification_url | string

Your webhook endpoint that handles transaction updates.

For more information, see notification_url.

gateway_info.payment_token | string

The JSON-encoded payment.token with the customer’s encrypted payment details, generated by the Apple Pay JS API.

For more information, see Apple Pay direct integration – Create an order and Apple Developer – ApplePayPaymentToken.

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

  • See also Payment methods – Bancontact.
  • Redirect only.

Parameters

type | string | required

The payment flow for the checkout process.
Options: redirect, paymentlink.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

gateway | string | required

The unique gateway identifier to direct the customer straight to the payment method.
Fixed value: MISTERCASH.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

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

  • See also Payment methods – Bancontact.
  • Redirect only.

Parameters

type | string | required

The payment flow for the checkout process.
Options: redirect, paymentlink.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

gateway | string | required

The unique gateway identifier to direct the customer straight to the payment method.
Options: MISTERCASH.

currency | string | required

The currency for the order.
Fixed value: EUR.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

gateway_info | object

qr_enabled = 1 invokes the qr_url.
This parameter contains a deeplink to Bancontact/MisterCash, which can be encoded into a QR image.
If the request is successful, you receive 2 links: a payment link and a qr_url.

customer | object | required

See customer (object).

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

JSON response

{
    "success": true,
    "data": {
        "transaction_id": 123456789
        "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": "Kraanspoor",
            "address2": "",
            "city": "Amsterdam",
            "country": "NL",
            "country_name": "The Netherlands",
            "email": "[email protected]",
            "first_name": "Simon",
            "house_number": "39C",
            "last_name": "Smit",
            "locale": "nl_NL",
            "phone1": "0208500500",
            "phone2": "00310000001",
            "state": "NH",
            "zip_code": "1033SC"
        },
        "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": 123456789
                "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"
    }
}

Bank Transfer

See also Payment methods – Bank transfer.

Bank Transfer - redirect

Parameters

type | string | required

The payment flow for the checkout process.
Options: direct, redirect, checkout, paymentlink.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

gateway | string | required

The unique gateway identifier to direct the customer straight to the payment method.
Fixed value: BANKTRANS.

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

  • If the email parameter is not provided, MultiSafepay cannot send the payment details to the customer.
  • The country parameter provides the customer a local bank account to pay to, where available.

Bank Transfer - direct

Parameters

type | string | required

The payment flow for the checkout process.
Options: direct, redirect, checkout, paymentlink.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

gateway | string | required

The unique gateway identifier to direct the customer straight to the payment method.
Fixed value: BANKTRANS.

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

  • If the email parameter is not provided, MultiSafepay cannot send the payment details to the customer.
  • The country parameter provides the customer a local bank account to pay to, where available.

disable_send_email (optional) | boolean | required

If emailing payment instructions to the customer yourself, set to true.
For MultiSafepay to email payment instructions, set to false.
Options: true, false.
Default: false.

Note: In the JSON response, it is important to send payment instructions to the customer yourself. Note that all parameters can be different for every single transaction. Do not store this information except for a specific transaction.

gateway_info | object

The customer data (issuer_id) required for conducting credit checks.

Contains:

reference | string | required

A unique number the customer must provide in the bank transfer for MultiSafepay to recognize the payment.

issuer_name | string | required

The name of MultiSafepay’s bank to send the funds to.

destination_holder_name | string | required

The account holder name for MultiSafepay’s bank account.

destination_holder_city | string | required

The city where the MultiSafepay bank account is registered.

destination_holder_country | string | required

The country where the MultiSafepay bank account is registered.

destination_holder_iban | string | required

The international bank account number (IBAN) to send the funds to.

destination_holder_swift | string | required

The bank identification code (BIC) to send the funds to.

account_holder_name | string | required

The customer’s name, if provided in the transaction request.

account_holder_city | string | required

The customer’s city, if provided in the transaction request.

account_holder_country | string | required

The customer’s country, if provided in the transaction request.

POST - /orders

{
    "type": "redirect",
    "order_id": "my-order-id-1",
    "gateway": "BELFIUS",
    "currency": "EUR",
    "amount": 1000,
    "description": "Test order description",
    "payment_options": {
       "notification_url": "http://www.example.com/client/notification?type=notification",
        "redirect_url": "http://www.example.com/client/notification?type=redirect",
        "cancel_url": "http://www.example.com/client/notification?type=cancel", 
        "close_window": true
    },
    "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": 123456789
        "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": "Simon",
            "address1": "Kraanspoor",
            "house_number": "39C",
            "zip_code": "1033SC",
            "city": "Amsterdam",
            "country": "NL",
            "country_name": "The 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": 123456789
            "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

See also Payment methods – Belfius.

Belfius - redirect

Parameters

type | string | required

The payment flow for the checkout process.
Options: direct, redirect, paymentlink.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

gateway | string | required

The unique gateway identifier to direct the customer straight to the payment method.
Fixed value: BELFIUS.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

Belfius - direct

Parameters

type | string | required

The payment flow for the checkout process.
Options: direct, redirect, paymentlink.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

gateway | string | required

The unique gateway identifier to direct the customer straight to the payment method.
Fixed value: BELFIUS.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

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": true
    },
    "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": true
    },
    "customer": {
        "locale": "nl_BE",
        "ip_address": "123.123.123.123",
        "forwarded_ip": "",
        "first_name": "Simon",
        "last_name": "Smit",
        "address1": "Kraanspoor",
        "house_number": "39C",
        "zip_code": "1033SC",
        "city": "Amsterdam",
        "country": "NL",
        "phone": "0208500500",
        "email": "[email protected]",
        "referrer": "https://example.com",
        "user_agent": "Mozilla/5.0 (Windows NT 6.3; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/38.0.2125.111 Safari/537.36"
    }
}

JSON Repsonse

{
  "success": true,
  "data": {
    "amount": 1000,
    "amount_refunded": 0,
    "costs": [
      {
        "amount":,
        "description": "",
        "transaction_id": 123456789
        "type": "SYSTEM"
      },
      {
        "amount":,
        "description": "",
        "transaction_id": 123456789
        "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": "The Netherlands",
      "email": "[email protected]",
      "first_name": "Simon",
      "house_number": "39C",
      "last_name": "Smit",
      "phone1": "0208500500",
      "locale": "nl_BE",
      "phone1": "0208500500",
      "zip_code": "1033SC"
    },
    "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": 123456789
    "payment_url": "https://www.cbc.be/olpayment?langWebSite=N&olpId=S132&olpCtx=%2FH8s4RM8GN%2FSKLOcUoTBBPus%2BWBbXCz9ChR12y5ozVDe8Rc70DjFQNQy2TaiSnTOEQkziFEQmgQy%2BHDxrqqzB%2F8I1yk5zE0%"
  }
}

CBC

See also Payment methods – CBC.

CBC - redirect

Parameters

type | string | required

The payment flow for the checkout process.
Options: direct, redirect, paymentlink.

gateway | string | required

The unique gateway identifier to direct the customer straight to the payment method.
Fixed value: CBC.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

CBC - direct

Parameters

type | string | required

The payment flow for the checkout process.
Options: direct, redirect, paymentlink.

gateway | string | required

The unique gateway identifier to direct the customer straight to the payment method.
Fixed value: CBC.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

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": true
    },
    "customer": {
        "locale": "it_IT",
         "ip_address": "123.123.123.123"
    }
}

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 cards

Parameters

type | string | required

The payment flow for the checkout process.
Options: direct, redirect, paymentlink.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

gateway | string | required

The unique gateway identifier to direct the customer straight to the payment method.
To retrieve gateway IDs, see Gateways.
Options: CREDITCARD, VISA, MASTERCARD.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

Note: The co-branded card logo only displays if the locale is correctly supplied.

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": true
  },
  "customer": {
    "locale": "nl_NL",
    "ip_address": "123.123.123.123"
  }
}

JSON response

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

Credit cards

Parameters

type | string | required

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

gateway | string | required

The gateway identifier.
Fixed value: CREDITCARD.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

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

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

JSON response

{
  "success": true,
  "data": {
    "amount": 9743,
    "amount_refunded": 0,
    "costs": [
      {
        "amount":,
        "description": "",
        "transaction_id": 123456789
        "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": "Simon",
      "house_number": "39C",
      "last_name": "Smit",
      "locale": "nl_NL",
      "phone1": "0208500500",
      "zip_code": "1033SC"
    },
    "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": 123456789
    "payment_url": "https://pushpayments.db.com/flow/eyJwYXlsb2FkIjp7ImlwaSI6IjE2QjIwREREMjE1NjE0QTc2Rjg0OTMwMDV="
  }
}

Request to Pay

See also Payment methods – Request to Pay.

Request to Pay - redirect

Parameters

type | string | required

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

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

gateway | string | required

The unique gateway identifier to direct the customer straight to the payment method.
Fixed value: DBRTP.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

Request to Pay - direct

type | string | required

The payment flow for the checkout process.
Options: direct.

payment_options | object | required

See payment_options (object).

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

  • See also Payment methods – Dotpay.
  • Redirect only.

Parameters

type | string | required

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

gateway | string | required

The unique gateway ID to direct the customer straight to the payment method.
Fixed value: DOTPAY.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

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": true
    },
    ...
    "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": true
    },
    ...
    "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": {
        "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/82v6HsoQhaR823uIZ7hexDMwQyielzLrdox/?lang=nl_NL"
    }
}

E-Invoicing

See also Payment methods – E-Invoicing.

E-Invoicing - direct

Parameters

type | string | required

The payment flow for the checkout process.
Options: direct, redirect.

gateway | string | required

The unique gateway ID to direct the customer straight to the payment method.
Fixed value: EINVOICE.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

delivery | object

See delivery (object).

shopping_cart | object

See shopping_cart.items (object).

items | object

See items (object).

checkout_options | object

The definitions for the VAT class.

gateway_info | object

The customer data (issuer_id) required for conducting credit checks.

Contains:

birthday | string

The customer’s date of birth.
Format: yyyy-mm-dd.

bank_account | string

The customer’s (formatted) international bank account number (IBAN).
This is required for credit checks.

phone | string

The customer’s phone number.
Required for credit checks and to contact the customer in case of non-payment.

email | string

The email address for sending payment instructions to the customer.

E-Invoicing - redirect

Parameters

type | string | required

The payment flow for the checkout process.
Options: direct, redirect.

gateway | string | required

The unique gateway ID to direct the customer straight to the payment method.
Fixed value: EINVOICE.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

delivery | object

See delivery (object).

shopping_cart | object

See shopping_cart.items (object).

items | object

See items (object).

checkout_options | object

The definitions for the VAT class.

gateway_info | object

The customer data (issuer_id) required for conducting credit checks.

Contains:

birthday | string

The customer’s date of birth.
Format: yyyy-mm-dd.

bank_account | string

The customer’s (formatted) international bank account number (IBAN).
This is required for credit checks.

phone | string

The customer’s phone number.
Required for credit checks and to contact the customer in case of non-payment.

email | string

The email address for sending payment instructions to the customer.

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

  • See also Payment methods – EPS.
  • Redirect only.

Parameters

type | string | required

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

gateway | string | required

The unique gateway ID to direct the customer straight to the payment method.
Fixed value: EPS.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

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

  • See also Payment methods – Giropay.
  • Redirect only.

Parameters

type | string | required

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

gateway | string | required

The unique gateway ID to direct the customer straight to the payment method.
Fixed value: GIROPAY.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

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": true
    },
    "customer": {
        "locale": "nl_NL",
        "ip_address": "123.123.123.123",
        "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 cards

  • See also Payment methods – Gift cards.
  • Redirect only.

Parameters

type | string | required

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

gateway | string | required

The unique gateway identifier to direct the customer straight to the payment method.
To retrieve gateway IDs, see Gateways.
Note: We only preselect the gift card supplied in the gateway.

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

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

manual | string | required

Fixed value: false.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

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

  • See also Payment methods – iDEAL QR.
  • Redirect only.

Note: The test environment is not available for iDEAL QR. You can only test transactions in the live environment.

  • If the min_amount parameter is not set, the amount value is used as the min_amount and vice versa.
  • If the max_amount parameter is not set, the amount is used as the max_amount.
  • If you set both min_amount and max_amount parameters, the amount value is ignored.

Parameters

type | string | required

The payment flow for the checkout process.
Options: redirect, direct.

gateway | string | required

The unique gateway identifier to direct the customer straight to the payment method.
Fixed value: iDEALQR.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

gateway_info | object

The customer data (issuer_id) required for conducting credit checks.

Contains:

qr_size | integer

The size of the QR image in pixels. Sizes are between 100 and 2000 pixels. If the value does not meet this rule, default is used.
Default: 250.

allow_multiple | boolean

Set if a specific QR code can be used more than once.

allow_change_amount | boolean

Set if customers can change the amount to pay. Often used for donations.
Required parameters: max_amount, or min_amount, or both.

min_amount | string

Set the minimum amount if allow_change_amount is set to true.
The min_amount must not be more than the amount.
If you only use min_amount, the amount must be more than the min_amount. That is, the amount = max_amount.

max_amount | string

Set the maximum amount if allow_change_amount option is set to true.
If you only use max_amount, the amount must be less than the max_amount.

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

JSON response

{
  "success": true,
  "data": {
    "amount": 1000,
    "amount_refunded": 0,
    "costs": [
      {
        "amount":,
        "description": "",
        "transaction_id": 123456789
        "type": "SYSTEM"
      }
    ],
    "created": "2020-01-14T12:08:43",
    "currency": "EUR",
    "custom_info": {
      "custom_1": null,
      "custom_2": null,
      "custom_3": null
    },
    "customer": {
      "address1": "Kraanspoor",
      "address2": "",
      "city": "Amsterdam",
      "country": "NL",
      "country_name": "The Netherlands",
      "email": "[email protected]",
      "first_name": "Simon",
      "house_number": "39C",
      "last_name": "Smit",
      "locale": "en_US",
      "phone1": "0208500500",
      "phone2": "00310000001",
      "state": "NH",
      "zip_code": "1033SC"
    },
    "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_bic": "string",
      "account_holder_name": null,
      "account_iban": "*** 1234",
      "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": 123456789
    "payment_url": "https://www.abnamro.nl/en/ideal-betalen/index.html?randomizedstring=8641247395&trxid=1150001181473373"
  }
}

iDEAL

See also Payment methods – iDEAL.

iDEAL - redirect

Customers are redirected to a MultiSafepay payment page where they can select iDEAL as a payment method.

Parameters

type | string | required

The payment flow for the checkout process.
Options: direct, redirect, checkout, paymentlink.

gateway | string | required

The unique gateway ID to direct the customer straight to the payment method.
Fixed value: IDEAL.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency for the payment.
Fixed value: EUR.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

iDEAL - direct

Customers select iDEAL and the issuing bank on the checkout page, and are then directed to the issuer’s payment page.

Parameters

type | string | required

The payment flow for the checkout process.
Options: direct.

gateway_info | object | required

Contains:

issuer_id | integer | required

The unique identifier of the issuer.

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

JSON response

{
  "success": true,
  "data": {
    "transaction_id": 123456789
    "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": "Simon",
      "last_name": "Smit",
      "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": "*** 1234"
    },
    "costs": [
      {
        "transaction_id": 123456789
        "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

See also Payment methods – ING Home’Pay.

ING Home’Pay - direct

Parameters

type | string | required

The payment flow for the checkout process.
Options: direct, redirect, paymentlink.

gateway | string | required

The unique gateway identifier to direct the customer straight to the payment method.
Fixed value: INGHOME.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

ING Home’Pay - redirect

Parameters

type | string | required

The payment flow for the checkout process.
Options: direct, redirect, paymentlink.

gateway | string | required

The unique gateway identifier to direct the customer straight to the payment method.
Fixed value: INGHOME.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

custom_info | object

See custom_info (object).

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

See also Payment methods – Klarna.

The old Klarna environment only supports redirect orders.

The new Klarna payments environment supports redirect orders, and direct orders if using a custom itegration.

JSON requests are the same for both environments.

Klarna - redirect

Parameters

type | string | required

The payment flow for the checkout process.
Options: redirect, direct.

gateway | string | required

The unique gateway ID to direct the customer straight to the payment method.
To retrieve gateway IDs, see Gateways.
Fixed value: KLARNA.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

items | object

See items (object).

manual | string | required

Fixed value: false.

gateway_info | object | required

The customer data (issuer_id) required for conducting credit checks.

Contains:

birthday | object | required

The customer’s date of birth.
In the Netherlands and Belgium, this is required for credit checks.
Format: yyyy-mm-dd.

gender | string | required

The customer’s personal title.
Options: mr, mrs, miss.

phone | string | required

The customer’s phone number.
Required for credit checks and to contact the customer in case of non-payment.

email | string | required

The email address for sending payment instructions to the customer.

payment_options | object | required

See payment_options (object).

plugin | object | required

See plugin (object).

customer | object | required

See customer (object).

delivery | object

See delivery (object).

shopping_cart | object

See shopping_cart.items (object).

checkout_options | object

The definitions for the VAT class.

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": true
    },
    "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": true
    },
    "customer": {
        "locale": "nl_BE",
        "ip_address": "123.123.123.123",
        "forwarded_ip": "",
        "first_name": "Simon",
        "last_name": "Smit",
        "address1": "Kraanspoor",
        "house_number": "39C",
        "zip_code": "1033SC",
        "city": "Amsterdam",
        "country": "NL",
        "phone": "0208500500",
        "email": "[email protected]",
        "referrer": "https://example.com",
        "user_agent": "Mozilla/5.0 (Windows NT 6.3; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/38.0.2125.111 Safari/537.36"
    }
}

JSON Repsonse

{
  "success": true,
  "data": {
    "amount": 1000,
    "amount_refunded": 0,
    "costs": [
      {
        "amount":,
        "description": "",
        "transaction_id": 123456789
        "type": "SYSTEM"
      },
      {
        "amount":,
        "description": "",
        "transaction_id": 123456789
        "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": "The Netherlands",
      "email": "[email protected]",
      "first_name": "Simon",
      "house_number": "39C",
      "last_name": "Smit",
      "phone1": "0208500500",
      "locale": "nl_BE",
      "phone1": "0208500500",
      "zip_code": "1033SC"
    },
    "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": 123456789
    "payment_url": "https://www.kbc.be/olpayment?langWebSite=N&olpId=S132&olpCtx=%2FH8s4RM8GN%2FSKLOcUoTBBPus%2BWBbXCz9ChR12y5ozVDe8Rc70DjFQNQy2TaiSnTOEQkziFEQmgQy%2BHDxrqqzB%2F8I1yk5zE0%"
  }
}

KBC

See also Payment methods – KBC.

KBC - redirect

Parameters

type | string | required

The payment flow for the checkout process.
Options: direct, redirect, paymentlink.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

gateway | string | required

The unique gateway identifier to direct the customer straight to the payment method.
Fixed value: KBC.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

KBC - direct

Parameters

type | string | required

The payment flow for the checkout process.
Options: direct, redirect, paymentlink.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

gateway | string | required

The unique gateway identifier to direct the customer straight to the payment method.
Fixed value: KBC.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

manual | string | required

Fixed value: false.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

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": true
  },
  "customer": {
    "locale": "nl_NL",
    "ip_address": "123.123.123.123"
  }
}

JSON response

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

Maestro

  • See also Payment methods – Maestro.
  • Redirect only.

Parameters

type | string | required

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

gateway | string | required

The gateway identifier.
Fixed value: MAESTRO.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

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": true
  },
  "customer": {
    "locale": "nl_NL",
    "ip_address": "123.123.123.123"
  }
}

JSON response

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

Mastercard

  • See also Payment methods – Mastercard.
  • Redirect only.

Parameters

type | string | required

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

gateway | string | required

The gateway identifier.
Fixed value: MASTERCARD.

Note: We also offer a generic CREDITCARD gateway. This can save space in mobile checkouts, but customers can’t immediately see which credit cards are supported. When the customer enters the first digits of their card number, the relevant credit card logo appears automatically.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

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

See also Payment methods – Pay After Delivery.

Pay After Delivery - redirect

Parameters

type | string | required

The payment flow for the checkout process.
Fixed value: redirect.

gateway | string | required

The unique gateway ID to direct the customer straight to the payment method.
Fixed value: PAYAFTER.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

items | object

See items (object).

manual | string | required

Fixed value: false.

gateway_info | object | required

The customer data (issuer_id) required for conducting credit checks.

Contains:

birthday | object | required

The customer’s date of birth.
In the Netherlands and Belgium, this is required for credit checks.
Format: yyyy-mm-dd.

bankaccount | string | required

The customer’s formatted international bank account number (IBAN).
This is required for credit checks.

phone | string | required

The customer’s phone number.
Required for credit checks and to contact the customer in case of non-payment.

email | string | required

The email address for sending payment instructions to the customer.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

delivery | object

See delivery (object).

shopping_cart | object

See shopping_cart.items (object).

checkout_options | object

The definitions for the VAT class.

custom_info | object

See custom_info (object).

Pay After Delivery - direct

Parameters

type | string | required

The payment flow for the checkout process.
Fixed value: direct.

gateway | string | required

The unique gateway ID to direct the customer straight to the payment method.
Fixed value: PAYAFTER.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

manual | string | required

Fixed value: false.

gateway_info | object | required

The customer data (issuer_id) required for conducting credit checks.

Contains:

birthday | object | required

The customer’s date of birth.
In the Netherlands and Belgium, this is required for credit checks.
Format: yyyy-mm-dd.

bankaccount | string | required

The customer’s formatted international bank account number (IBAN).
This is required for credit checks.

phone | string | required

The customer’s phone number.
Required for credit checks and to contact the customer in case of non-payment.

email | string | required

The email address for sending payment instructions to the customer.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

delivery | object

See delivery (object).

shopping_cart | object

See shopping_cart.items (object).

items | object

See items (object).

checkout_options | object

The definitions for the VAT class.

custom_info | object

See custom_info (object).

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": true
    },
    "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": true
    },
    "customer": {
        "locale": "nl_NL",
        "ip_address": "123.123.123.123",
        "forwarded_ip": "",
        "first_name": "Simon",
        "last_name": "Smit",
        "address1": "Kraanspoor",
        "house_number": "39C",
        "zip_code": "1033SC",
        "city": "Amsterdam",
        "state": "NH",
        "country": "NL",
        "phone": "0208500500",
        "email": "[email protected]",
        "referrer": "https://example.com",
        "user_agent": "Mozilla/5.0 (Windows NT 6.3; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/38.0.2125.111 Safari/537.36"
    }
}

JSON response

{
  "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": "Simon",
      "house_number": "39C",
      "last_name": "Smit",
      "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": 123456789
    "payment_url": "https://www.paypal.com/cgi-bin/webscr?cmdmsp=_express-checkout&token=EC-8K013819T00365502LLL-msp"
  }
}

PayPal

See also Payment methods – PayPal.

PayPal - redirect

Once the customer has completed payment, the status changes to Completed. The financial_status remains Initialized, and during this status you cannot ship the order. You must first set the order to Completed for both the status and financial_status and then ship the order.

Parameters

type | string | required

The payment flow for the checkout process.
Options: direct, redirect, checkout, paymentlink.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

gateway | string | required

The unique gateway ID to direct the customer straight to the payment method.
Fixed value: PAYPAL.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

Note: To be eligible for PayPal Seller Protection, for the following countries the transaction request must include the state parameter in the customer’s address.

PayPal - direct

Parameters

type | string | required

The payment flow for the checkout process.
Options: direct, redirect, checkout, paymentlink.

gateway | string | required

The unique gateway ID to direct the customer straight to the payment method.
Fixed value: PAYPAL.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

Note: To be eligible for PayPal Seller Protection, for the following countries the transaction request must include the state parameter in the customer’s address.

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

Parameters

type | string | required

The payment flow for the checkout process.
Options: direct, redirect, paymentlink.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

gateway | string | required

The unique gateway ID to direct the customer straight to the payment method.
Fixed value: SANTANDER.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

gateway_info | object

The customer data (issuer_id) required for conducting credit checks.

Contains:

birthday | object | required

The customer’s date of birth.
In the Netherlands and Belgium, this is required for credit checks.
Format: yyyy-mm-dd.

gender | string | required

The customer’s personal title.
Options: mr, mrs, miss.

phone | string | required

The customer’s phone number.
Required for credit checks and to contact the customer in case of non-payment.

email | string | required

The email address for sending payment instructions to the customer.

custom_info | object

See custom_info (object).

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": true
    },
    "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": true
    },
    "customer": {
        "locale": "nl_NL",
        "ip_address": "123.123.123.123",
        "forwarded_ip": ""
    },
    "gateway_info": {
        "account_id": "NL87ABNA0000000001",
        "account_holder_name": "Example",
        "account_holder_iban": "NL87ABNA0000000001",
        "emandate": "mandateID"
    }
}

JSON response

{
  "success": true,
  "data": {
    "transaction_id": 123456789
    "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": "*** 1234",
    },
    "costs": [
      {
        "transaction_id": 123456789
        "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

See also Payment methods – SEPA Direct Debit.

SEPA Direct Debit - redirect

Parameters

type | string | required

The payment flow for the checkout process.
Options: direct, redirect, checkout, paymentlink.

gateway | string | required

The unique gateway ID to direct the customer straight to the payment method.
Fixed value: IDEAL.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

gateway_info | object

The customer data (issuer_id) required for conducting credit checks.

Contains:

account_id | string

The international bank account number (IBAN) to be charged for the transaction.

account_holder_name | string

The name of the account holder to be charged for the transaction.

account_holder_iban | string

The international bank account number (IBAN) to be charged for the transaction.

emandate | string

The e-mandate (for your own adminstration).

recurring_id | string

The unique identifier for the recurring payment.

SEPA Direct Debit - direct

Parameters

type | string | required

The payment flow for the checkout process.
Options: direct, redirect, checkout, paymentlink.

gateway | string | required

The unique gateway ID to direct the customer straight to the payment method.
Fixed value: DIRDEB.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

gateway_info | object

The customer data (issuer_id) required for conducting credit checks.

Contains:

account_id | string

The international bank account number (IBAN) to be charged for the transaction.

account_holder_name | string

The name of the account holder to be charged for the transaction.

account_holder_iban | string

The international bank account number (IBAN) to be charged for the transaction.

emandate | string

The e-mandate (for your own adminstration).

recurring_id | string

The unique identifier for the recurring payment.

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": true
    },
    "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": true
    },
    "customer": {
        "locale": "de_DE",
        "ip_address": "123.123.123.123",
        "forwarded_ip": "",
        "first_name": "Simon",
        "last_name": "Smit",
        "address1": "Kraanspoor",
        "house_number": "39C",
        "zip_code": "1033SC",
        "city": "Amsterdam",
        "country": "NL",
        "phone": "0208500500",
        "email": "[email protected]",
        "referrer": "https://example.com",
        "user_agent": "Mozilla/5.0 (Windows NT 6.3; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/38.0.2125.111 Safari/537.36"
    }
}

JSON response

{
  "success": true,
  "data": {
    "amount": 9743,
    "amount_refunded": 0,
    "costs": [
      {
        "amount":,
        "description": "",
        "transaction_id": 123456789
        "type": "SYSTEM"
      },
      {
        "amount":,
        "description": "",
        "transaction_id": 123456789
        "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": "The Netherlands",
      "email": "[email protected]",
      "first_name": "Simon",
      "house_number": "39C",
      "last_name": "Smit",
      "locale": "de_DE",
      "phone1": "0208500500",
      "zip_code": "1033SC"
    },
    "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": 123456789
    "payment_url": "https://payv2.multisafepay.com/connect/99wi0OTuiCaTY2nwEiEOybWpVx8MNwrJ75c/?lang=de_DE",
    "cancel_url": "http://www.example.com/client/notification?type=cancel"
  }
}

SOFORT

See also Payment methods – SOFORT Banking.

SOFORT - redirect

Parameters

type | string | required

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

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

gateway | string | required

The unique gateway ID to direct the customer straight to the payment method.
Fixed value: DIRECTBANK.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.
For supported currencies, see About SOFORT Banking.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

SOFORT - direct

Parameters

type | string | required

The payment flow for the checkout process.
Options: direct.

gateway | string | required

The unique gateway ID to direct the customer straight to the payment method.
Fixed value: DIRECTBANK.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.
For supported currencies, see About SOFORT Banking.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

manual | string | required

Fixed value: false.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

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

  • See also Payment methods – Trustly.
  • Redirect only.

Parameters

type | string | required

The payment flow for the checkout process.
Options: redirect, direct, paymentlink.

gateway | string | required

The unique gateway identifier to direct the customer straight to the payment method.
Fixed value: TRUSTLY.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

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

  • See also Payment methods – TrustPay.
  • Redirect only.

Parameters

type | string | required

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

gateway | string | required

The unique gateway identifier.
Fixed value: TRUSTPAY.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

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": true
  },
  "customer": {
    "locale": "nl_NL",
    "ip_address": "123.123.123.123"
  }
}

JSON response

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

Visa

  • See also Payment methods – Visa.
  • Redirect only.

Parameters

type | string | required

The payment flow for the checkout process.
Fixed value: redirect.

gateway | string | required

The gateway identifier.
Fixed value: VISA.

Note: We also offer a generic CREDITCARD gateway. This can save space in mobile checkouts, but customers can’t immediately see which credit cards are supported. When the customer enters the first digits of their card number, the relevant credit card logo appears automatically.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

Discounts

For post-payment methods, MultiSafepay validates the shopping_cart. If you want to apply a discount before sending a payment request, we recommend submitting the discount in the unit price.

Avoid adding discounts as a separate discount rule because, for partial refunds, you can’t undo the negative amount.

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

Order rule discounts (non-refundable)

For all payment methods except post-payment methods, the main way of adding a discount before submitting a transaction request is to add it as an order rule.

For post-payment methods, adding a discount as an order rule or a separate discount rule can create a conflict for partial refunds, especially when the discount is a percentage. You cannot undo or partially refund the negative amount.

Instead, add discounts as a unit price.

Unit price discounts

For post-payment methods, add discounts as a unit price.

No negative order rule is created, which avoids the refund conflict that can arise if you add discounts as separate discount rules or order rules.

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

Accounts

Partners and primary account holders can use these endpoints to perform actions on affiliated accounts.

GET /accounts/{affiliated_id}/balances

Response

{
    "data": [
        {
            "account_id": 12345678,
            "amount_available": 0,
            "amount_reserved": 0,
            "currency": "EUR",
            "id": "qzk7mjd92idka",
            "modified": "2021-01-01 12:34:13"
        }
    ],
    "page": {
        "total": 1
    },
    "success": true
}

Balances

As a partner or primary account holder, use this endpoint to retrieve the balance of an affiliated account.

By default, balance requests are disabled. To enable balance requests for your account, email your account manager at [email protected]

For authentication, use your account API key.

Parameters

affiliated_id | query parameter | required

The account ID of the affiliated account.

amount_available | integer

The available balance in cents.
This is the total balance minus the reserved balance.

amount_reserved | integer

The reserved balance in cents.

currency | string

The currency of the balance.
Includes every available currency in the affiliate’s account. Format: ISO-4217 currency codes.

id | string

The balance ID.

modified | string

The timestamp of the last modification of the balance.
Modifications include incoming payments, refunds, charges, and payouts.
Format: ISO-8601.

POST /accounts/{affiliated_id}/charges

{
   "amount" : 10000,
   "currency" : "EUR",
   "order_id" : "Charge_id_1234",
   "description" : "Monthly fees",
   "var1" : null,
   "var2" : null,
   "var3" : null
}

Response

{
    "data": {
        "amount": 10000,
        "costs": [],
        "created": "2021-06-29T11:00:48",
        "currency": "EUR",
        "debit_credit": "D",
        "description": "Monthly fees",
        "financial_status": "completed",
        "order_id": "Charge_id_1234",
        "payment_method": null,
        "site_id": null,
        "status": "completed",
        "transaction_id": "1234567",
        "type": "merchant_settlement",
        "var1": null,
        "var2": null,
        "var3": null 
    },
    "success": true
}

Charges

As a partner or primary account holder, use this endpoint to move funds from an affiliated account’s balance to your own.

By default, charges are disabled. To enable charges for your account, email your account manager at [email protected]

For authentication, use your account API key.

Parameters

affiliated_id | query parameter | required

The account ID of the affiliated account you want to charge.

amount | integer | required

The amount to charge in cents.

currency | string | required

The currency you want to charge the affiliated account in.
Format: ISO-4217 currency codes.

order_id | string | required

Your unique identifier for the charge.

description | string | optional

A description of the transaction, which is displayed in both your account and the affiliated account.

var1 | string | optional

A variable for storing additional data.

var2 | string | optional

A second variable for storing additional data.

var3 | string | optional

A third variable for storing additional data.

POST /accounts/{affiliated_id}/payouts

{
   "amount" : 10000,
   "currency" : "EUR",
   "order_id" : "Payout_id_1234",
   "description" : "Monthly payout",
   "var1" : null,
   "var2" : null,
   "var3" : null
}

Response

{
    "data": {
        "amount": 10000,
        "costs": [
            {
                "amount": 50,
                "currency": "EUR"
            }
        ],
        "created": "2021-06-29T12:46:23",
        "currency": "EUR",
        "debit_credit": "D",
        "description": "Monthly payout",
        "financial_status": "reserved",
        "order_id": "Payout_id_1234",
        "payment_method": "BANKTRANS",
        "site_id": null,
        "status": "reserved",
        "transaction_id": "1234567",
        "type": "withdrawal",
        "var1": null,
        "var2": null,
        "var3": null
    },
    "includes": {
        "bankaccount": {
            "currency": "EUR",
            "holder_name": "test",
            "iban": "NL02ABNA0123456789",
            "id": "mk7uq33sl6hep"
        }
    },
    "success": true
}

Payouts

As a partner or primary account holder, use this endpoint to pay out funds from an affiliated account’s balance to a connected bank account.

By default, payouts for affiliated accounts are disabled. To enable payouts for your affiliated accounts, email your account manager at [email protected]

For authentication, use your account API key.

Parameters

affiliated_id | query parameter | required

The account ID of the affiliated account you want to pay out funds from.

amount | integer | required

The amount to pay out in cents.

currency | string | required

The currency of the payout.
Format: ISO-4217 currency codes.

order_id | string | required

Your unique identifier for the payout.

description | string | optional

A description of the transaction, which is displayed in the affiliated account.

var1 | string | optional

A variable for storing additional data.

var2 | string | optional

A second variable for storing additional data.

var3 | string | optional

A third variable for storing additional data.

Other requests

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": "123.123.123.123",
        "forwarded_ip": "",
        "first_name": "Simon",
        "last_name": "Smit",
        "address1": "Kraanspoor",
        "house_number": "39C",
        "zip_code": "1033SC",
        "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": "Simon",
        "last_name": "Smit",
        "address1": "Kraanspoor",
        "house_number": "39C",
        "zip_code": "1033SC",
        "city": "Amsterdam",
        "country": "NL",
        "phone": "0208500500",
        "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": "NL"
                        }
                    ]
                }
            ]
        }
    },
    "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

Submit data related to a Pay After Delivery order and customer for MultiSafepay to conduct a pre-check to determine whether to accept the order.

If not accepted, the customer must select another payment method to complete payment.

Parameters

type | string | required

The payment flow for the checkout process.
Options: direct.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

gateway | string | required

The unique gateway ID to direct the customer straight to the payment method.
To retrieve gateway IDs, see Gateways.

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

gateway_info | object | required

Contains:

issuer_id | string | required

The unique identifier of the gateway issuer.
See Retrieve gateway issuers.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

delivery | object | required

See delivery (object).

shopping_cart | object | required – or use items

See shopping_cart.items (object).

items | object | required – or use shopping_cart

See items (object).

GET - /categories

JSON response

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

Retrieve website categories

Retrieves a list of website categories.

Tokenization

Tokenization is the process of storing payment details as encrypted tokens for future payments, e.g. recurring transactions.

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

POST - /orders

{
    "type": "direct",
    "order_id": "my-order-id-1",
    "currency": "EUR",
    "recurring_id": "azbkvsE0up4",
    "recurring_model": "unscheduled",
    "amount": 1000,
    "description": "Create tokenization order",
    "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": "Create tokenization order",
                "transaction_id": 123456789
                "type": "SYSTEM"
            }
        ],
        "created": "2019-10-24T13:22:45",
        "currency": "EUR",
        "custom_info": {
            "custom_1": null,
            "custom_2": null,
            "custom_3": null
        },
        "customer": {
            "address1": "Kraanspoor",
            "address2": "",
            "city": "Amsterdam",
            "country": "NL",
            "country_name": "The Netherlands",
            "email": "[email protected]",
            "first_name": "Simon",
            "house_number": "39C",
            "last_name": "Smit",
            "locale": "nl_NL",
            "phone1": "0208500500",
            "phone2": "00310000001",
            "reference": "AutoQAReference",
            "state": "NH",
            "zip_code": "1033SC"
        },
        "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": 123456789
        "payment_url": " https://payv2.multisafepay.com/connect/99wi0OTuiCaTY2nwEiEOybWpVx8MNwrJ75c/?lang=nl_NL ",
        "cancel_url": " http://www.example.com/client/notification?type=cancel "
    }
}

Create tokenization order

Create a tokenization order.

Parameters

type | string | required

The payment flow for the checkout process.
Options: direct.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

recurring_id | string | required

The unique identifier for the recurring payment.

recurring_model | string | required

The recurring model.
Options: unscheduled, subscription, cardonfile.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

account_holder_name | string

The customer’s name here if provided in transaction request.

card_expiry_date | string

The expiry date on the credit card.

reason | string

Add a short text memo based on the capture reason of the order.

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

JSON response

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

Delete a token

Delete a token related to a single customer reference.

Parameter

token | string | required

The unique token identifier linked to the customer reference.

GET - /orders/{order_id}

JSON response

{
    "success": true,
    "data": {
        "amount": 10000,
        "amount_refunded": 0,
        "costs": [
            {
                "amount": ,
                "description": "Tokenization Test Order",
                "transaction_id": 123456789
                "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": "",
            "city": "Amsterdam",
            "country": "NL",
            "country_name": "The Netherlands",
            "email": "[email protected]",
            "first_name": "Simon",
            "house_number": "39C",
            "last_name": "Smit",
            "locale": "nl_NL",
            "phone1": "0208500500",
            "reference": "AutoQAReference",
            "zip_code": "1033SC"
        },
        "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": 123456789
    }
}

Retrieve order details

Retreive details about a tokenization order.

Parameter

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

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

Retrieve token details

Retreive information about a specific token.

Parameter

token | string | required

The unique token linked to the customer reference.

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

Retrieve all customer tokens

Retrieve all tokens related to a specific customer reference.

If there are lots of tokens, you can use the limit and offset parameters to limit the number of tokens retrieved.

Example: If limit is set to 15 and offset to 0, then 17 tokens are listed (tokens 0 to 16).

Parameter

token | string | required

The unique token identifier linked to the customer reference.

limit | integer | required

The number of tokens to list.
If empty, the default is 10.

offset | integer | required

The number of the token to start the list from.
If empty, the default is 0, i.e. the first token.

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": "123.123.123.123",
                "forwarded_ip": "",
                "first_name": "Simon",
                "last_name": "Smit",
                "address1": "Kraanspoor",
                "house_number": "39C",
                "zip_code": "1033SC",
                "city": "Amsterdam",
                "country": "NL",
                "birthday": "1970-07-10",
                "gender": "mr",
                "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"
    }
}

Specify recurring model

Create an original tokenization order using a specific recurring model:

  • Card on file (COF): The cardholder has authorized you to store their card details.
  • Subscription: Agreement or services that are billed at the end of your billing cycle.
  • Unscheduled: Event triggered for application, e.g. a mobile top-up when no credit is left on the phone.

Parameters

type | string | required

The payment flow for the checkout process.
Options: direct, redirect.

gateway | string | required

The unique gateway identifier to direct the customer straight to the payment method.
To retrieve gateway IDs, see Gateways.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

recurring_model | string | required

The recurring model.
Options: unscheduled, subscription, cardonfile.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

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

{
    "expiry_date": "2903"
}

JSON response

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

Update card expiry date

Update the credit card expiry date for a token when it expires.

Make a PATCH request with the required placeholders in the URL:

  • your_customer_reference: Your unique reference number for the customer.
  • your_token: The unique token identifier associated with the customer.

Parameter

expiry_date | integer | required

The updated expiry date.
Format: monthnumberdatenumber.
Example: December 2025 is formatted as 1225.

Reference

{
"customer": {
	"locale": "nl_NL",
	"ip_address": "123.123.123.123",
	"forwarded_ip": "",
	"first_name": "Simon",
	"last_name": "Smit",
	"gender": "mr",
	"birthday": "1970-07-10",
	"address1": "Kraanspoor",
	"address2": "",
	"house_number": "39C",
	"zip_code": "1033SC",
	"city": "Amsterdam",
	"country": "NL", 
	"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)

The customer’s personal information.

Contains:

Parameters

locale | string | required

Displays the correct language and payment methods on the payment page, and influences sending email templates. Format: ab_CD with ISO 639 language codes and ISO 3166 country codes.
Default: en_US.

ip_address | string | optional but recommended

The IP address of the customer.
Recommended for post-payment and credit card payment methods.
MultiSafepay validates customer IP addresses to help detect fraudulent payments.

forwarded_ip | string | required

The X-Forwarded-For header of the customer request when using a proxy.
For more information, see Validating customer IP addresses.

first_name | string | required

The customer’s first name.
Format: Minimum two characters.
We recommend always requiring the customer to provide their full name, instead of initials or abbreviations.

last_name | string | required

The customer’s last name.
Format: Minimum two characters.
We recommend always requiring the customer to provide their full name, instead of initials or abbreviations.

gender | string | required

The customer’s gender.

birthday | string | required

The customer’s birthday.

address1 | string | required

The first line of the customer’s address.

address2 | string | required

The second line of the customer’s address.

house_number | string | required

The customer’s house number.

zip_code | string | required

The customer’s ZIP/postal code.

city | string | required

The customer’s city of residence.

country | string | required

The customer’s country of residence.
Format: ISO 3166-1 country code.

phone | string | required

The customer’s phone number.

email | string | required

The customer’s email address.
Used to send Second Chance emails and to conduct fraud checks.

user_agent | string | required

A characteristic string that identifies a browser.

referrer | string | required

The unique identifier of where the user/browser originates from.

reference | string | For tokenization transactions: required

See Create token transaction.

"custom_info": {
      "custom_1": null,
      "custom_2": null,
      "custom_3": null

custom_info (object)

A placeholder parameter where you can include specific details related to the transaction. 

{
"delivery": {
        "first_name": "Testperson-nl",
        "last_name": "Approved",
        "address1": "Kraanspoor",
        "house_number": 39C,
        "zip_code": "1033 SC",
        "city": "Amsterdam",
        "country": "NL"
    
}

delivery (object)

The delivery information for the shipment.

Contains:

Parameters

first_name | string | required

The customer’s first name.
Format: Minimum two characters.
We recommend always requiring the customer to provide their full name, instead of initials or abbreviations.

last_name | string | required

The customer’s last name.
Format: Minimum two characters.
We recommend always requiring the customer to provide their full name, instead of initials or abbreviations.

address1 | string | required

The first line of the customer’s address.

house_number | string | required

The customer’s house number.

zip_code | string | required

The customer’s ZIP/postal code.

city | string | required

The customer’s city of residence.

country | string | required

The customer’s country of residence.
Format: ISO 3166-1 country code.

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

items (object)

If you want to specify the items in the order without including a full [shopping_cart object]((/api/#shopping-cart-items), you can add a single items line.

Note: Post-payment methods require the full shopping_cart object.

Parameter

items | object | required

A specification of the order items to display on your checkout page.

{
	"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", 
		"notification_method": "POST",
		"close_window": true,
	}
}

payment_options (object)

URLs for sending notifications to, or to redirect customers to.

Contains:

Parameters

notification_url | string | required

Endpoint for MultiSafepay to send status updates and other notifications to.
For more information, see notification_url.

redirect_url | string | required

The page the customer is redirected to after completing payment.
If the transaction status changes to Uncleared, the customer is also redirected to your thank-you page.
Note: Customers never see an Uncleared status. They always experience the payment as successful.

cancel_url | string | required

The page the customer is redirected to if the payment fails.

notification_method | string | optional

Enables push notifications.
Options: POST, GET.
Default: GET.

close_window | bool | optional

To display the MultiSafepay payment page in a new window that automatically closes after the customer completes payment, set to True.
Options: True, False.

plugin (object)

This object is required for community-developed integrations.

Contains:

Parameters

shop | string | required

The ecommerce platform that you use.

plugin_version | string | required

The version of the plugin.

shop_version | string | required

The version of the ecommerce webshop you use.

partner | string | required

The name of the third party that developed the ecommerce webshop.

shop_root_url | string | required

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

settings (object)

Contains:

Parameters

hide_logo | boolean | optional

Hides header logo

iframe_mode | boolean | optional

Hides various sections, e.g. logo, header

hide_flags | boolean | optional

Hides flags container.

hide_powered | boolean | optional

Hides powered link.

hide_cart | boolean | optional

Hides cart container.

hide_btn_cancel | boolean | optional

Hides Cancel button.

hide_cc_logos | boolean | optional

Hides credit card logos.

hide_btn_all_methods | boolean | optional

Hides All methods button.

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

shopping_cart.items (object)

All items in the shopping cart, including the tax class.
If you have a custom integration, include the complete specification of the shopping_cart.

Contains:

Parameters

name | string | required

The customer’s name.

description | string | required

A description of the item that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

unit_price | float | required

The unit price (in decimals) of the item, excluding VAT.
Format: Maximum 10 decimal places.

quantity | integer | required

The number of units of the item.

merchant_item_id | string | required

Fixed value: msp-shipping.

tax_table_selector | string | required

The tax ruling.

Note: A 0 value throws an error: ‘1029: Invalid tax rate specified for item’.
Format: The tax_table_selector and tax_table names are both strings.

weight | string | required

The weight of the item.

options | string | required

An array of objects including id, set_id, value, price, type, and price_type.

value | integer | required

The weight of the item corresponding to the unit.
Example: unit= KG, value= 12. The weight of the item is 12 kilograms.

unit | string | required

The unit of weight, e.g. KG.

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

Note: Server to server must first be activated by the Risk Team.

3D-enabled requests

Parameters

type | string | required

The payment flow for the checkout process.
Options: direct.

gateway | string | required

The unique gateway ID to direct the customer straight to the payment method.
Options: VISA, MASTERCARD, AMEX, MAESTRO, CREDITCARD.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

gateway_info | object

Contains:

card_number | string

The customer’s full credit card number.

card_holder_name | string

The name of the cardholder on the credit card.

card_expiry_date | string

The expiry date on the credit card.

card_cvc | string

The card verification code (CVC) is a 3 or 4 digit number 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.

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": "123.123.123.123",
        "forwarded_ip": "",
        "first_name": "Simon",
        "last_name": "Smit",
        "address1": "Kraanspoor",
        "address2": "",
        "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": {
        "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": 123456789
        "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": "The Netherlands",
      "email": "[email protected]",
      "first_name": "Simon",
      "house_number": "39C",
      "locale": "nl_NL",
      "phone1": "0208500500",
      "zip_code": "1033SC"
    },
    "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": 123456789
    "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 card requests

Parameters

type | string | required

The payment flow for the checkout process.
Options: direct.

gateway | string | required

The unique gateway ID to direct the customer straight to the payment method.
Options: VISA, MASTERCARD, AMEX, MAESTRO, CREDITCARD.
When set to CREDITCARD, the type of credit card is detected based on the first four digits.

customer | object | required

See customer (object).

gateway_info | object

Contains:

card_number | string

The customer’s full credit card number.

card_holder_name | string

The name of the cardholder on the credit card.

card_expiry_date | string

The expiry date on the credit card.

card_cvc | string

The card verification code (CVC) is a 3 or 4 digit number 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.

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

Parameters

type | string | required

The payment flow for the checkout process.
Options: direct.

gateway | string | required

The unique gateway ID to direct the customer straight to the payment method.
Fixed value: CREDITCARD.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

gateway_info | object

Contains:

card_number | string

The customer’s full credit card number.

card_holder_name | string

The name of the cardholder on the credit card.

card_expiry_date | string

The expiry date on the credit card.

card_cvc | string

The card verification code (CVC) is a 3 or 4 digit number 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.

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": true
    },
   "customer": {
       "locale": "nl_NL",
       "ip_address": "123.123.123.123",
       "first_name": "Simon",
       "last_name": "Smit",
       "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": 123456789
        "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": "Simon",
            "last_name": "Smit",
            "address1": "Kraanspoor",
            "address2": "",
            "house_number": "39C",
            "zip_code": "1033SC",
            "city": "Amsterdam",
            "state": "NH",
            "country": "NL",
            "country_name": "The Netherlands",
            "phone1": "0208500500",
            "phone2": "00310000001",
            "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": 123456789
                "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 to false

Use Flexible 3D to set whether or not to complete the transaction with 3D Secure verification.

To disable 3D Secure, in the POST /orders request > gateway_info object, set the flexible_3d parameter to false.

Notes:

  • Activating Flexible 3D Secure overrides Dynamic 3D settings, so that payments are not enrolled with a 3D authentication.

  • We no longer support Flexible 3D for merchants based in Europe due to PSD2 regulations.

Parameters

type | string | required

The payment flow for the checkout process.
Options: direct.

gateway | string | required

The unique gateway ID to direct the customer straight to the payment method.
Options: VISA, MASTERCARD.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

gateway_info | object | required

Defines certain customer data (payment details).

Contains:

flexible_3d | boolean | required

True, enable the 3D Secure authentication. False, disable the 3D Secure authentication.

term_url | string | required

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": "123.123.123.123",
        "forwarded_ip": "",
        "first_name": "Simon",
        "last_name": "Smit",
        "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": "The Netherlands",
      "email": "[email protected]",
      "first_name": "Simon",
      "house_number": "39C",
      "last_name": "Smit",
      "locale": "nl_NL",
      "phone1": "0208500500",
      "zip_code": "1033SC"
    },
    "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": 123456789
    "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: Flexible 3D set to true

Use Flexible 3D to set whether or not to complete the transaction with 3D Secure verification.

To enable 3D Secure, in the POST /orders request > gateway_info object, set the flexible_3d parameter to true.

Notes:

  • Activating Flexible 3D Secure overrides Dynamic 3D settings, so that payments are not enrolled with a 3D authentication.

  • We no longer support Flexible 3D for merchants based in Europe due to PSD2 regulations.

Parameters

type | string | required

The payment flow for the checkout process.
Options: direct.

gateway | string | required

The unique gateway ID to direct the customer straight to the payment method.
Option: CREDITCARD.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

gateway_info | object | required

Contains:

flexible_3d | boolean | required

  • true: enables 3D Secure verification
  • false: disable 3D Secure verification

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": true
   }, 
   "customer": {
       "locale": "nl_NL",
       "ip_address": "123.123.123.123",
       "first_name": "Simon",
       "last_name": "Smit",
       "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": {
       "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 to false

Use Flexible 3D to set whether or not to complete the transaction with 3D Secure verification.

To enable 3D Secure, in the POST /orders request > gateway_info object, set the flexible_3d parameter to false.

Notes:

  • Activating Flexible 3D Secure overrides Dynamic 3D settings, so that payments are not enrolled with a 3D authentication.

  • We no longer support Flexible 3D for merchants based in Europe due to PSD2 regulations.

Parameters

type | string | required

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

gateway | string | required

The unique gateway ID to direct the customer straight to the payment method.
Options: VISA, MASTERCARD.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

gateway_info | object | required

Contains:

flexible_3d | boolean | required

  • true: enables 3D Secure verification
  • false: disable 3D Secure verification

term_url | string | required

The URL to inform the card issuer where to redirect the authorisation query.

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": "123.123.123.123",
       "first_name": "Simon",
       "last_name": "Smit",
       "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": {
       "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 to true

Use Flexible 3D to set whether or not to complete the transaction with 3D Secure verification.

To enable 3D Secure, in the POST /orders request > gateway_info object, set the flexible_3d parameter to true.

Notes:

  • Activating Flexible 3D Secure overrides Dynamic 3D settings, so that payments are not enrolled with a 3D authentication.

  • We no longer support Flexible 3D for merchants based in Europe due to PSD2 regulations.

Parameters

type | string | required

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

gateway | string | required

The unique gateway ID to direct the customer straight to the payment method.
Options: VISA, MASTERCARD.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

gateway_info | object | required

Contains:

flexible_3d | boolean | required

  • true: enables 3D Secure verification
  • false: disable 3D Secure verification

term_url | string | required

The URL to inform 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": true
    },
    "customer": {
        "locale": "nl_NL",
        "ip_address": "123.123.123.123",
        "referrer": "https://example.com",
        "user_agent": "Mozilla/5.0 (Windows NT 6.3; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/38.0.2125.111 Safari/537.36"
    }
}

JSON response

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

The payment flow for the checkout process.
Options: redirect, direct, checkout, paymentlink.

gateway | string | required

The unique gateway ID to direct the customer straight to the payment method.
To retrieve gateway IDs, see Gateways.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 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 | required

See payment_options (object).

customer | object | required

See customer (object).

locale | string

Displays the correct language and payment methods on the payment page, and influences sending email templates. Format: ab_CD with ISO 639 language codes and ISO 3166 country codes.
Default: en_US.

ip_address | string

The customer’s IP address.
Recommended for post-payment and credit card payment methods. MultiSafepay validates customer IP addresses to help detect fraudulent payments.

close_window | bool | optional

To display the MultiSafepay payment page in a new window that automatically closes after the customer completes payment, set to True.
Options: True, False.

See also Manual Capture.

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": 123456789
        "order_id": "my-order-id-01"
    }
}

Full capture

Parameters

amount | integer | required

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

new_order_id | integer / string

Your unique identifier for the order.
Format: Maximum 50 characters.

new_order_status | string

The updated 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 your MultiSafepay account (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 | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

See also Manual Capture.

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": 123456789
        "order_id": "my-order-id-01"
    }
}

Partial capture

Parameter

amount | integer | required

The amount (in cents) 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 your MultiSafepay account (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 | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

See also Manual Capture.

GET - /orders/

JSON response

{
    "success": true,
    "data": {
        "transaction_id": 123456789
        "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": "Simon",
            "last_name": "Smit",
            "address1": "Kraanspoor",
            "address2": "",
            "house_number": "39C",
            "zip_code": "1033SC",
            "city": "Amsterdam",
            "state": "NH",
            "country": "NL",
            "country_name": "The Netherlands",
            "phone1": "0208500500",
            "phone2": "00310000001",
            "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": 123456789
                "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"
            }
        ]
    }
}

Set order status of captured transaction

Parameter

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

See also Manual Capture.

GET - /orders/{order_id}

JSON response

{
    "success": true,
    "data": {
        "transaction_id": 123456789
        "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": "Simon",
            "last_name": "Smit",
            "address1": "Kraanspoor",
            "address2": "",
            "house_number": "39C",
            "zip_code": "1033SC",
            "city": "Amsterdam",
            "state": "NH",
            "country": "NL",
            "country_name": "The Netherlands",
            "phone1": "0208500500",
            "phone2": "00310000001",
            "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": 123456789
                "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"
            }
        ]
    }
}

Set order status of authorized transaction

Parameter

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

See also Manual Capture.

PATCH - /capture/{order_id}

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

JSON response

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

Cancel an authorized or reserved transaction

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.

See also Manual Capture.

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": true
    },
    "customer": {
        "locale": "en_US"
    }
}

JSON response

{
  "success": true,
  "data": {
    "order_id": "test-123",
    "payment_url": "https://devpayv2.multisafepay.com/connect/89QENbhQYcJoP2CO0kx6pSRrw8v2JFnTynr/?lang=nl_NL"
  }
}

Generate a payment link. Your MultiSafepay account creates a unique transaction to match to the payment.

See Send second chance emails.

Payment links no longer send Second Chance emails by default. You must include the Second Chance script in the JSON request. See the Second Chance JSON script on the right-hand side.

Parameters

type | string | required

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

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

gateway (optional) | string

The unique gateway ID to direct the customer straight to the payment method.
To retrieve gateway IDs, see Gateways.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

second_chance | object | optional

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

Contains:

send_email | boolean | optional

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": true
    },
    "customer": {
        "locale": "nl_NL",
        "ip_address": "123.123.123.123",
        "forwarded_ip": "",
        "first_name": "Simon",
        "last_name": "Smit",
        "address1": "Kraanspoor",
        "address2": "",
        "house_number": "39C",
        "zip_code": "1033SC",
        "city": "Amsterdam",
        "state": "NH",
        "country": "NL",
        "birthday": "1970-07-10",
        "gender": "mr",
        "phone": "0208500500",
        "email": "[email protected]",
        "referrer": "https://example.com",
        "user_agent": "Mozilla/5.0 (Windows NT 6.3; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/38.0.2125.111 Safari/537.36"
    }
}

JSON response

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

The payment flow for the checkout process.
Options: redirect, direct, checkout, paymentlink.

gateway | string | required

The unique gateway ID to direct the customer straight to the payment method.
To retrieve gateway IDs, see Gateways.

order_id | integer / string | required

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.

amount | integer | required

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

description | string | required

The order description that appears in your MultiSafepay account and on the customer’s bank statement (if supported by the customer’s bank).
Format: Maximum 200 characters.
HTML is not supported. Use the items or shopping_cart objects for this.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

close_window | bool | optional

To display the MultiSafepay payment page in a new window that automatically closes after the customer completes payment, set to True.
Options: True, False.

See also Zero Authorization.

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": "",
      "city": "Amsterdam",
      "country": "NL",
      "country_name": "The Netherlands",
      "email": "[email protected]",
      "first_name": "Simon",
      "house_number": "39C",
      "last_name": "Smit",
      "locale": "nl_NL",
      "phone1": "0208500500",
      "phone2": "00310000001",
      "state": "NH",
      "zip_code": "1033SC"
    },
    "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": 123456789
    "var1": null,
    "var2": null,
    "var3": null
  }
}

Order Status

Parameter

order_id | string / integer

Your unique identifier for the order.
If the values are numbers only, the type is integer. Otherwise, it is string.
Format: Maximum 50 characters.

See also Zero Authorization.

Feedback

Propose a change on GitHubexternal-link-icon or
send an email to [email protected]

Other languages

For an explanation in another language, contact your account manager.