1. Home
  2. API reference

API reference

Welcome to the MultiSafepay API reference (JSON gateway).

Navigating the reference

Use the table of contents on the left to navigate endpoints and requests.

The middle column provides detailed information about each request, including parameters and data types.

The right column shows example JSON requests and responses.

Using our API

You can use our API, for example, to:

Advanced requests include:

You can also use our API to build a custom integration. You can test your integration in the TEST environment.

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

Note: Tokens are active for 600 seconds.

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.

Required transaction details

As a PSP, MultiSafepay is obliged by law to monitor transactions, merchants, and customers. We have to know the type of product or service involved in each transaction, and who is buying and selling.

For each transaction, you must include details about the product and the customer’s:

  • Name
  • IP address
  • Country
  • Email address

If you fail to provide this information, we may need to carry out extra screening and may request copies of invoices for specific orders.

GET - /gateways

JSON response

{
  "success": true,
  "data":[
    {
      "id": "VISA",
      "description": "Visa"
    },
    {
      "id": "IDEAL",
      "description": "iDEAL"
    }
  ]
}

Retrieve activated gateways

Retrieve all activated gateways.

Parameters

include | string | optional | query parameter

By default, only one activated gift card is included in the response.

To include all activated gift cards in the response, specify coupons.

Options: coupons

country | string | optional | query parameter

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

currency | string | optional | query parameter

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

amount | integer | optional | query parameter

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

GET - /gateways/{id}

JSON response

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

Retrieve a gateway

Retrieve a gateway by its ID.

Parameters

id | string | required | query parameter

The unique identifier of the requested gateway.

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

Note: The list of issuers may differ when requested via the test environment.

Parameters

code | string | required

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

Create and manage 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 in the payment method’s environment.

For more information, see Difference between direct and redirect.

Note: All fields must be completed correctly.

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":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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

order_id | string | required

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

gateway | string | required

The unique gateway identifier for 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.

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.

Contains:

account | string | optional

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

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

second_chance | object | optional

See Send second chance emails.

shopping_cart.items | optional

See shopping_cart.items object.

Response

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

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":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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,
        "amount":0,
        "description":"iDEAL Transactions",
        "type":"SYSTEM"
      }
    ],
    "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 | string | required

Your unique identifier for the order.
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 for 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.
See Retrieve gateway issuers.

payment_options | object | required

See payment_options (object).

shopping_cart.items | optional

See shopping_cart.items object.

Response

transaction_id | integer

MultiSafepay’s identifier for the transaction (also known as the PSP ID).

created | string

The timestamp for when the order was created.

var1 / var2 / var3 | string

Variables for storing additional data.

amount_refunded | integer

The amount refunded to the customer.

status | string

The order status.

financial_status | string

The transaction status of the order.

reason | string

fastcheckout | string

Value: NO.

modified | string

The timestamp when the order was last modified.

customer | object

See customer (object).

payment_details | object

See payment_details (object).

costs | object

See costs (object).

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

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,
        "amount":0.19,
        "description":"Refund order 258655825 for TEST TEST",
        "type":"internal",
        "created":"2019-03-01T16:14:02",
        "status":"completed"
      }
    ],
    "related_transactions":[
      {
        "amount":200,
        "costs":[
          {
            "amount":19,
            "description":"EURO 0.19 per refund",
            "type":"SYSTEM",
            "currency":"EUR",
            "status":"reserved"
          }
        ],
        "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"
      }
    ]
  }
}

Get order details

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

Parameters

order_id | string | required

The unique identifier of the requested order.
Format: Maximum 50 characters.

Response

transaction_id | integer

MultiSafepay’s identifier for the transaction (also known as the PSP ID).

created | string

The timestamp for when the order was created.

currency | string

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

amount | integer

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

description | string

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.

var1 / var2 / var3 | string

Variables for storing additional data.

items | object

See items (object).

status | string

The order status.

financial_status | string

The transaction status of the order.

reason | string | required

fastcheckout | string

Value: NO.

modified | string

The timestamp when the order was last modified.

customer | object

See customer (object).

payment_details | object

See payment_details (object).

related_transactions | object

Information about linked transactions.

Contains:

costs | object

See costs (object).

payment_methods | object

See payment_methods (object).

PATCH - /orders/{order_id}

{
  "id":"MSP12345",
  "status":"shipped",
  "tracktrace_code":"3SMSP0123456789",
  "tracktrace_url":"https://tracktrace-url.com/",
  "carrier":"MSP Logistics",
  "ship_date":"01-01-1911",
  "reason":"Fulfilled by warehouse",
  "invoice_id":"AB12345",
  "invoice_url":"https://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 order status of the order.
Options: cancelled, shipped.

tracktrace_code | string | optional

The track and trace code provided by the shipping company.

tracktrace_url | string | optional

The track and trace URL 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

The reason for updating the order.

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.

PATCH - /orders/{order_id}

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

JSON response

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

Cancel an order

Cancel a pretransaction based on the order_id.

Parameters

status | string | required

The order status.
Value: cancelled.

exclude_order | integer | optional

Sets the outcome of the cancellation.
To cancel the pretransaction, set to 1.

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":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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 to send to a customer.
Your MultiSafepay account creates a unique transaction to match to the payment.

Parameters

type | string | required

The payment flow for the checkout process.
Valuementlink` (makes the transaction appear in your MultiSafepay account under Tools > Payment link generator).

order_id | string | required

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

gateway | string | optional

The unique gateway identifier for 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.

Note: Payment links no longer send second chance emails by default. You must include the Second Chance script in the JSON request as per the example request.

Contains:

send_email | boolean | optional

  • true: Sends a Second Chance email to the customer.
  • false or empty: No email reminder is sent.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

Response

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

POST - /orders

{
  "type":"paymentlink",
  "order_id":"test-123",
  "gateway":"",
  "currency":"EUR",
  "amount":1000,
  "description":"Test order description",
  "days_active":14,
  "second_chance":{
    "send_email":true
  },
  "payment_options":{
    "notification_url":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://www.example.com/client/notification?type=cancel",
    "close_window":true
  },
  "customer":{
    "locale":"en_US"
  }
  }

The lifetime of payment links for MultiSafepay payment pages is how long the link remains valid for the customer to complete payment. This applies to redirect orders only. The default is 30 days, after which the link expires. Except for:

To cancel a payment link, see Cancel an order.

Second Chance
You cannot edit payment links in Second Chance emails, because the session_id of the initial transaction has already been used. You can only edit the link in the initial POST /orders request.

If set for under 24 hours:

  • days_active: The payment link displays an error message when opened.
  • seconds_active: The second email is still sent, even though the payment link it contains is no longer valid. This can’t be changed.

Parameters

Include in the main body of your POST /orders request:

days_active | string | optional

The number of days the payment link is valid for.
If not set, or if seconds_active is also set, seconds_active is used.
If neither days_active nor seconds_active is set, the default is used.
Default: 30 days.

seconds_active | string | optional

The number of seconds the payment link is valid for.
Example: 86.400 seconds_active = 1 days_active.
If set and larger than 0, seconds_active overrides days_active.
If neither days_active nor seconds_active is set, the default is used.
Default: 30 days.

description | string | optional

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":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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 templates

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

type | string | required

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

order_id | string | required

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

gateway | string | required

The unique gateway identifier for 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.

manual | string | required

Value: false.

payment_options | object | required

See payment_options (object).

template | object | optional

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

Contains:

  • settings | object

    See settings (object).

  • header | object

  • cover | object

  • background | object

  • body | object

  • container | object

  • cart | object

  • payment_form | object

  • buttons | object

    Contains:

template_id | string | optional

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

customer | object | required

See customer (object).

Response

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

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

Send second chance emails

If a customer initiated a transaction but didn’t complete 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 in each transaction request.

See also Adjust payment link lifetimes.

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 places 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 does not suppress Second Chance emails.

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

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


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

Validate shopping cart

Applies to all payment methods except pay later methods.

Parameters

checkout_options | object | required

Contains:

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.

Discounts and refunds

POST - /orders/{order_id}/refunds

{
  "currency": "EUR",
  "amount": "500",
  "description": "",
  "refund_order_id": "refund-order-id-1234",
  "var1": "test-string1",
  "var2": "test-string2",
  "var3": "test-string3"
}

JSON response

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

Refund an order

Process a full or partial refund for an order.

Parameters

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.

refund_order_id | string | optional

Your unique identifier for the refund. If this is not set, the order_id is used.
Format: Maximum 50 characters.

var1 / var2 / var3 | string | optional

Variables for storing additional data with the refund.

Response

transaction_id | integer

MultiSafepay’s identifier for the original transaction for payment (also known as the PSP ID for the original order).

refund_id | integer

MultiSafepay’s identifier for the transaction for refund (also known as the PSP ID for the refund).

POST - /orders/{order_id}/refunds

{
  "checkout_data":{
    "items":[
      {
        "name":"Geometric Candle Holders",
        "description":"",
        "unit_price":90,
        "quantity":3,
        "merchant_item_id":"111111",
        "tax_table_selector":"none",
        "weight":{
          "unit":"KG",
          "value":12
        },
      {
        "name":"Geometric Candle Holders",
        "description":"",
        "unit_price":-90,
        "quantity":2,
        "merchant_item_id":"111111",
        "tax_table_selector":"none",
        "weight":{
          "unit":"KG",
          "value":12
        }
      },
      ...
      {
        "name":"Flat Rate - 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 pay later orders that include a shopping_cart object.

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

  2. Make a POST /orders/{id}/refunds request:

    • For Klarna, add a duplicate object for each item you need to refund with a negative unit_price.
    • For all other pay later methods, set a negative quantity.

Note: Make sure you provide the exact same merchant_item_id, tax_table_selector, and unit_price.

The example refunds two out of three geometric candle holders.

Parameter

checkout_data | object | required

Contains the original shopping_cart.items object and duplicate objects for items to be refunded.
See shopping_cart.items object.

POST - /orders

{
  "type":"redirect",
  "gateway":"PAYAFTER",
  "order_id":"my-order-id-1",
  "currency":"EUR",
  "amount":17424,
  ...
  "shopping_cart":{
    "items":[
      {
        "name":"Geometric Candle Holders",
        "description":"",
        "unit_price":90.00,
        "quantity":2,
        "merchant_item_id":"111111",
        "tax_table_selector":"none",
        "weight":{
          "unit":"KG",
          "value":12
        }
      },
      {
        "name":"20% discount on all items",
        "description":"Discount",
        "unit_price":-43.56,
        "quantity":1,
        "merchant_item_id":"discount",
        "tax_table_selector":"none",
        "weight":{
          "unit":"KG",
          "value":0
        }
      }
    ]
  },
  "checkout_options":{
    "tax_tables":{
      "default":{
        "shipping_taxed":true,
        "rate":0.21
      },
      "alternate":[
        {
          "name":"BTW21",
          "rules":[
            {
              "rate":0.21
            }
          ]
        },
        {
          "name":"none",
          "rules":[
            {
              "rate":0.00
            }
          ]
        }
      ]
    }
  }
}

Discount with order rule

For all payment methods except pay later methods, the main way of adding a discount before submitting a transaction request is to add it as an order rule (non-refundable).

For pay later 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.

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

Parameters

type | string | required

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

gateway | string | required

The unique gateway identifier for the payment method.
Options: VISA, MASTERCARD, AMEX, MAESTRO, CREDITCARD.

order_id | string | required

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

currency | string | required

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

amount | integer | required

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

shopping_cart.items | required

See shopping_cart.items object.

checkout_options | object | required

The definitions for the VAT class.

Discount with unit price

For pay later methods, add discounts as a unit price. The example request is for a 20% discount on all unit prices.

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.

Parameters

type | string | required

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

gateway | string | required

The unique gateway identifier for the payment method.
Options: VISA, MASTERCARD, AMEX, MAESTRO, CREDITCARD.

order_id | string | required

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

currency | string | required

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

amount | integer | required

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

shopping_cart.items | required

See shopping_cart.items object.

checkout_options | object | required

The definitions for the VAT class.

POST /orders

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

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

{
  "type":"redirect",
  "order_id":"order_id_0000001",
  "gateway":"",
  "currency":"EUR",
  "amount":10000,
  "description":"Manual Capture Test",
  "capture":"manual",
  "payment_options":{
    "notification_url":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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 orders

See Manual Capture.

This only applies to specific credit card payment methods, including MasterCard, VISA and Maestro.

Create a Manual Capture order

Parameters

type | string | required

The payment flow for the checkout process.
Options: redirect, direct, paymentlink (makes the transaction appear in your MultiSafepay account under Tools > Payment link generator).

order_id | string | required

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

gateway | string | required

The unique gateway identifier for 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.

capture | string

A manual capture has been generated.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

POST - /orders/{order_id}/capture

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

JSON response

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

Full capture

Parameters

amount | integer | optional

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

For full captures, you can omit the attribute or specify the original amount.

new_order_id | string | optional

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

new_order_status | string | required

The updated status of the order.

invoice_id | string | optional

Update an existing order with a reference to your internal invoice ID.
The invoice ID is added to reports generated from your MultiSafepay account.
Format: Maximum 50 characters.

tracktrace_code | string | optional

The track and trace code linked to the shipment of the order.

carrier | string | optional

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

reason | string | optional

The reason for capturing the order.

description | string | optional

Can be used to store additional information.

Response

transaction_id | integer

MultiSafepay’s identifier for the transaction (also known as the PSP ID).

order_id | string | required

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

POST - /orders/{order_id}/capture

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

JSON response

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

Partial capture

Parameter

amount | integer | optional

The amount (in cents) to charge.

For partial captures, specify the amount to capture.

new_order_id | string | optional

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

new_order_status | string | required

The updated status of the order.

invoice_id | string | optional

Update an existing order with a reference to your internal invoice ID.
The invoice ID is added to reports generated from your MultiSafepay account.
Format: Maximum 50 characters.

tracktrace_code | string | optional

The track and trace code linked to the shipment of the order.

carrier | string | optional

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

reason | string | optional

The reason for capturing the order.

order_id | string | required

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

description | string | optional

Can be used to store additional information.

PATCH - /capture/{order_id}

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

JSON response

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

Cancel an authorized or reserved transaction

Parameters

status | string | required

The order status.

To cancel an authorized or reserved transaction, specify cancelled.

reason | string | required

The reason for cancelling the order.

description | string | optional

Use to provide additional information.

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,
        "amount":2.83,
        "description":"",
        "type":"SYSTEM"
      }
    ],
    "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 | string | required

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

Response

transaction_id | integer

MultiSafepay’s identifier for the transaction (also known as the PSP ID).

created | string

The timestamp for when the order was created.

currency | string

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

amount | integer

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

description | string

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.

var1 / var2 / var3 | string

Variables for storing additional data.

items | object

See items (object).

amount_refunded | integer

The amount refunded to the customer.

status | string

The order status.

financial_status | string

The transaction status of the order.

reason | string | required

fastcheckout | string

Value: NO.

modified | string

The timestamp when the order was last modified.

customer | object | required

See customer (object).

payment_details | object

See payment_details (object).

costs | object

See costs (object).

related_transactions | string

Information about linked transactions.

payment_methods | object

See payment_methods (object).

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,
        "amount":0,
        "description":"",
        "type":"SYSTEM"
      }
    ],
    "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 | string | required

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

Response

transaction_id | integer

MultiSafepay’s identifier for the transaction (also known as the PSP ID).

created | string

The timestamp for when the order was created.

currency | string

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

amount | integer

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

description | string

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.

var1 / var2 / var3 | string

Variables for storing additional data.

items | object

See items (object).

amount_refunded | integer

The amount refunded to the customer.

status | string

The order status.

financial_status | string

The transaction status of the order.

reason | string | required

The reason for capturing the order.

fastcheckout | string

Value: NO.

modified | string

The timestamp when the order was last modified.

customer | object | required

See customer (object).

payment_details | object

See payment_details (object).

costs | object

See costs (object).

related_transactions | string

Information about linked transactions.

payment_methods | object

See payment_methods (object).

POST - /orders

{
  "order_id": 1018051,
  "type": "direct",
  "currency": "EUR",
  "amount": "100",
  "description": "Test order description",
  "customer": {
    "locale": "en_US",
    "reference": "Your customer reference"
  },
  "payment_options":{
    "notification_url":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://www.example.com/client/notification?type=cancel"
  },
  "payment_data": {
    "payload": "eyJnYXRld2F5IjoiSURFQUwiLCJjdXN0b21lciI6eyJicm93c2VyIjp7ImphdmFfZW5hYmxlZCI6MCwiamF2YXNjcmlwdF9lbmFibGVkIjoxLCJsYW5ndWFnZSI6ImVuLUdCIiwic2NyZWVuX2NvbG9yX2RlcHRoIjoyNCwic2NyZWVuX2hlaWdodCI6MTQ0MCwic2NyZWVuX3dpZHRoIjozNDQwLCJ0aW1lX3pvbmUiOi0xMjAsInVzZXJfYWdlbnQiOiJNb3ppbGxhLzUuMCAoTWFjaW50b3NoOyBJbnRlbCBNYWMgT1MgWCAxMF8xNV83KSBBcHBsZVdlYktpdC81MzcuMzYgKEtIVE1MLCBsaWtlIEdlY2tvKSBDaHJvbWUvOTMuMC40NTc3LjYzIFNhZmFyaS81MzcuMzYiLCJjb29raWVzX2VuYWJsZWQiOjEsInBsYXRmb3JtIjoiTWFjSW50ZWwifSwibG9jYWxlIjoiZW5fVVMifSwiZmllbGRzIjp7ImV4dHZhcjgiOiIwMDMxIn0sImVuY3J5cHRlZCI6ZmFsc2UsImFwcGxpY2F0aW9uIjoiQVBJQ09OTkNPTVA6VjEifQ==",
    "gateway": "<relevant-gateway>"
  }
}

JSON response

{
  "success": true,
  "data": {
    "amount": 100,
    "amount_refunded": 0,
    "costs": [
      {
        "amount": 0.44,
        "description": "0.44 For iDEAL Transactions",
        "transaction_id": 2856265,
        "type": "SYSTEM"
      }
    ],
    "created": "2021-09-24T12:09:28",
    "currency": "EUR",
    "custom_info": {
      "custom_1": null,
      "custom_2": null,
      "custom_3": null
    },
    "customer": {
      "address1": null,
      "address2": null,
      "city": null,
      "country": null,
      "country_name": null,
      "email": "",
      "first_name": null,
      "house_number": null,
      "last_name": null,
      "locale": "en_US",
      "phone1": null,
      "phone2": "",
      "state": null,
      "zip_code": null
    },
    "description": "product description",
    "fastcheckout": "NO",
    "financial_status": "initialized",
    "items": null,
    "modified": "2021-09-24T12:09:28",
    "order_id": "connect-comp614da3d8a00e8",
    "payment_details": {
      "account_holder_name": null,
      "account_iban": "https://testpayv2.multisafepay.com/simulator/ideal?trxid=2826044090080124&ideal=prob&issuerid=0031&merchantReturnURL=https%3A%2F%2Ftestpay%2Emultisafepay%2Ecom%2Fdirect%2Fcomplete%2F%3Fmspid%3D4990929",
      "account_id": null,
      "external_transaction_id": 2826044090080124,
      "issuer_id": "0031",
      "recurring_flow": null,
      "recurring_id": null,
      "recurring_model": null,
      "type": "IDEAL"
    },
    "payment_methods": [
      {
        "amount": 100,
        "currency": "EUR",
        "description": "product description",
        "external_transaction_id": 2826044090080124,
        "payment_description": "iDEAL",
        "status": "initialized",
        "type": "IDEAL"
      }
    ],
    "reason": "",
    "reason_code": "",
    "related_transactions": null,
    "status": "initialized",
    "transaction_id": 4990929,
    "var1": null,
    "var2": null,
    "var3": null,
    "payment_url": "https://testpayv2.multisafepay.com/simulator/ideal?trxid=2826044090080124&ideal=prob&issuerid=0031&merchantReturnURL=https%3A%2F%2Ftestpay%2Emultisafepay%2Ecom%2Fdirect%2Fcomplete%2F%3Fmspid%3D4990929"
  }
}

Payment Component orders

Create a Payment Component order.

Parameters

order_id | string | required

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

type | string | required

The payment flow for the checkout process.
Value: direct

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

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.

customer | object | optional

See customer (object).

payment_options | object | required

See payment_options (object).

payment_data | object | required

The response to the getPaymentData() Payment Component method.

The payment_data object contains the payload and gateway identifier.

See Payment Component integration manual – Step 3: Create an order:

Response

costs | object

See costs (object).

created | string

The timestamp for when the order was created.

custom_info | object

See custom_info (object).

fastcheckout | string

financial_status | string

The transaction status of the order.

items | object

See items (object).

modified | string

The timestamp when the order was last modified.

payment_details | object

See payment_details (object).

payment_methods | object

See payment_methods (object).

reason | string

related_transactions | object

Information about linked transactions.

status | string

The order status.

transaction_id | integer

MultiSafepay’s identifier for the transaction (also known as the PSP ID).

var1 / var2 / var3 | string

Variables for storing additional data.

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

Recurring payments orders

Recurring payments is the process of storing payment details as encrypted tokens for subsequent payments.

This section lists the API requests and parameters for different recurring payments orders.

See also Manage tokens.

POST - /orders

{
  "type":"direct",
  "order_id":"my-order-id-1",
  "gateway":"",
  "currency":"EUR",
  "recurring_id":"azbkvsE0up4",
  "recurring_model":"unscheduled",
  "amount":1000,
  "description":"Create tokenization order",
  "payment_options":{
    "notification_url":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://www.example.com/client/notification?type=cancel",
    "close_window":true
  },
  "customer":{
    "reference":"AutoQAReference"
  }
}

JSON response

{
  "success":true,
  "data":{
    "amount":1000,
    "amount_refunded":0,
    "costs":[
      {
        "transaction_id":123456789,
        "amount":0.6,
        "description":"Create tokenization order",
        "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 recurring payments orders

Create recurring payments orders.

Parameters

type | string | required

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

order_id | string | required

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

gateway | string | required

The unique gateway identifier for the payment method.
Options:

  • American Express: AMEX
  • Bancontact: MISTERCASH
  • Credit cards: CREDITCARD
  • iDEAL: IDEAL
  • Maestro: MAESTRO
  • Mastercard: MASTERCARD
  • SEPA Direct Debit: DIRDEB
  • Sofort: DIRECTBANK
  • Visa: VISA

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: cardonfile, subscription, unscheduled.

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

Response

amount_refunded | integer

The amount refunded to the customer.

costs | object

See costs (object).

created | string

The timestamp for when the order was created.

custom_info | object

See custom_info (object).

fastcheckout | string

Value: NO.

financial_status | string

The transaction status of the order.

items | object

See items (object).

modified | string

The timestamp when the order was last modified.

payment_details | object

See payment_details (object).

payment_methods | object

See payment_methods (object).

reason | string

related_transactions | object

Information about linked transactions.

status | string

The order status.

transaction_id | integer

MultiSafepay’s identifier for the transaction (also known as the PSP ID).

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

cancel_url | string

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

GET - /orders/{order_id}

JSON response

{
  "success":true,
  "data":{
    "amount":10000,
    "amount_refunded":0,
    "costs":[
      {
        "transaction_id":123456789,
        "amount":0,
        "description":"Tokenization Test Order",
        "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":"Test tokenization 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
  }
}

Get recurring payment order details

Retreive details about a recurring payment order.

Parameter

order_id | string | required

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

Response

amount | integer

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

amount_refunded | integer

The amount refunded to the customer.

costs | object

See costs (object).

created | string

The timestamp for when the order was created.

currency | string

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

custom_info | object

See custom_info (object).

customer | object | required

See customer (object).

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.

fastcheckout | string

Value: NO.

financial_status | string

The transaction status of the order.

items | object

See items (object).

modified | string

The timestamp when the order was last modified.

payment_details | object

See payment_details (object).

payment_methods | object

See payment_methods (object).

reason | string | required

related_transactions | object

Information about linked transactions.

status | string

The order status.

transaction_id | integer

MultiSafepay’s identifier for the transaction (also known as the PSP ID).

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":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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":"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",
    "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 initial recurring payment 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 | string | required

Your unique identifier for the order.
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).

Response

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

POST - /orders

{
  "type":"direct",
  "gateway":"CREDITCARD",
  "order_id":"order-1",
  "currency":"EUR",
  "amount":1000,
  "description":"product description",
  "payment_options":{
    "notification_url":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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" 
}

3D-enabled requests

Parameters

type | string | required

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

gateway | string | required

The unique gateway identifier for the payment method.
Options: VISA, MASTERCARD, AMEX, MAESTRO, CREDITCARD.

order_id | string | required

Your unique identifier for the order.
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":"CREDITCARD",
  "order_id":"order-1",
  "currency":"EUR",
  "amount":1000,
  "description":"product description",
  "payment_options":{
    "notification_url":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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 identifier for the payment method.
Value: CREDITCARD.

order_id | string | required

Your unique identifier for the order.
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":10,
  "gateway":"CREDITCARD",
  "description":"Test order description",
  "payment_options":{
    "notification_url":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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":"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"
  },
  "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":"https://www.example.com/client/notification?type=cancel&transactionid=apitool_"
  }
}

Direct: Flexible 3D enabled

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.

order_id | string | required

Your unique identifier for the order.
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 for the payment method.
Option: CREDITCARD.

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. The payment is classified as 3D Secure Result: Enrolled Liability.
  • false: Disables 3D Secure verification. The payment is classified as “Not Enrolled, Liability”.

Response

amount_refunded | integer

The amount refunded to the customer.

costs | object

See costs (object).

fastcheckout | string

Value: NO.

financial_status | string

The transaction status of the order.

items | object

See items (object).

modified | string

The timestamp when the order was last modified.

payment_details | object

See payment_details (object).

payment_methods | object

See payment_methods (object).

reason | string

related_transactions | object

Information about linked transactions.

status | string

The order status.

transaction_id | integer

MultiSafepay’s identifier for the transaction (also known as the PSP ID).

var1 / var2 / var3 | string

Variables for storing additional data.

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

cancel_url | string

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

POST - /orders

{
  "type":"direct",
  "gateway":"VISA",
  "order_id":"my-test-order-01",
  "currency":"EUR",
  "amount":100,
  "description":"test product description",
  "payment_options":{
    "notification_url":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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":"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"
  },
  "gateway_info":{
    "flexible_3d":false,
    "card_number":"4111111111111111",
    "card_holder_name":"MultiSafepay",
    "card_expiry_date":"2412",
    "term_url":"https://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":1234,
      "last4":1111,
      "card_expiry_date":2412
    },
    "costs":[
      {
        "transaction_id":123456789,
        "amount":0.0,
        "description":"0.0 % for visa credit card transactions",
        "type":"SYSTEM"
      }
    ],
    "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 disabled

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 identifier for the payment method.
Options: VISA, MASTERCARD.

order_id | string | required

Your unique identifier for the order.
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.

Response

transaction_id | integer

MultiSafepay’s identifier for the transaction (also known as the PSP ID).

created | string

The timestamp for when the order was created.

var1 / var2 / var3 | string

Variables for storing additional data.

items | object

See items (object).

amount_refunded | integer

The amount refunded to the customer.

status | string

The order status.

financial_status | string

The transaction status of the order.

reason | string

fastcheckout | string

Value: NO.

modified | string

The timestamp when the order was last modified.

custom_info | object

See custom_info (object).

payment_details | object

See payment_details (object).

costs | object

See costs (object).

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

cancel_url | string

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

POST - /orders

{
  "type":"redirect",
  "gateway":"MASTERCARD",
  "order_id":"my-order-id-01",
  "currency":"EUR",
  "amount":100,
  "description":"test product description",
  "payment_options":{
    "notification_url":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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":"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"
  },
  "gateway_info":{
    "flexible_3d":true,
    "term_url":"https://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 enabled

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 identifier for the payment method.
Options: VISA, MASTERCARD.

order_id | string | required

Your unique identifier for the order.
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.

Response

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

POST - /orders

{
  "type":"redirect",
  "gateway":"VISA",
  "order_id":"my-order-id-1",
  "currency":"EUR",
  "amount":100,
  "description":"test product description",
  "payment_options":{
    "notification_url":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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":"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"
  },
  "gateway_info":{
    "flexible_3d":false,
    "term_url":"https://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 disabled

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 identifier for the payment method.
Options: VISA, MASTERCARD.

order_id | string | required

Your unique identifier for the order.
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.

Response

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

POST - /orders

{
  "type":"direct",
  "order_id":"my-order-id-1",
  "currency":"EUR",
  "amount":1000,
  "gateway":"CREDITCARD",
  "description":"product description",
  "payment_options":{
    "notification_url":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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":"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"
  },
  "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":[
      {
        "transaction_id":123456789,
        "amount":0,
        "description":"",
        "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":"https://www.example.com/client/notification?type=cancel"
  }
}

Credit card requests

Parameters

type | string | required

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

order_id | string | required

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

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.

gateway | string | required

The unique gateway identifier for 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.

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.

Response

amount_refunded | integer

The amount refunded to the customer.

costs | object

See costs (object).

fastcheckout | string

Value: NO.

financial_status | string

The transaction status of the order.

items | object

See items (object).

modified | string

The timestamp when the order was last modified.

payment_details | object

See payment_details (object).

payment_methods | object

See payment_methods (object).

reason | string

related_transactions | object

Information about linked transactions.

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

cancel_url | string

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

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 orders

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

See Split payments.

Parameters

type | string | required

The payment flow for the checkout process.
Options: direct, redirect, paymentlink (makes the transaction appear in your MultiSafepay account under Tools > Payment link generator).

gateway | string | required

The unique gateway identifier for the payment method.
To retrieve gateway IDs, see Gateways.

order_id | string | required

Your unique identifier for the order.
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.

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.

Response

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

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":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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 orders

See Zero Authorization.

Parameters

type | string | required

The payment flow for the checkout process.
Options: redirect, direct, paymentlink (makes the transaction appear in your MultiSafepay account under Tools > Payment link generator).

order_id | string | required

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

gateway | string | required

The unique gateway identifier for 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

Value: 0.

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

Value: false.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

Response

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

GET - /orders/{order_id}

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

Get zero authorization order details

Parameter

order_id | integer | required

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

Response

amount | integer

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

amount_refunded | integer

The amount refunded to the customer.

costs | object

See costs (object).

created | string

The timestamp for when the order was created.

currency | string

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

custom_info | object

See custom_info (object).

customer | object | required

See customer (object).

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.

fastcheckout | string

Value: NO.

financial_status | string

The transaction status of the order.

items | object

See items (object).

modified | string

The timestamp when the order was last modified.

payment_details | object

See payment_details (object).

payment_methods | object

See payment_methods (object).

reason | string

related_transactions | object

Information about linked transactions.

status | string

The order status.

transaction_id | integer

MultiSafepay’s identifier for the transaction (also known as the PSP ID).

var1 / var2 / var3 | string | optional

Variables for storing additional data.

Payment method examples

 
This section contains example POST /orders requests for all supported payment methods, both direct and redirect orders (where relevant).

Note: All fields must be completed correctly.

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

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

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":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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":[
      {
        "transaction_id":2045938,
        "amount":2600,
        "description":"",
        "type":"SYSTEM"
      },
      {
        "amount":2600,
        "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"
  }
}

AfterPay

See also Payment methods – AfterPay.

AfterPay - redirect

Parameters

type | string | required

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

gateway | string | required

The unique gateway ID that immediately directs the customer to the payment method.
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.

items | object

See items (object).

manual | string | required

Value: false.

shopping_cart | object

See shopping_cart.items (object).

checkout_options | object

The definitions for the VAT class.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

delivery | object

See delivery (object).

Response

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

AfterPay - direct

Parameters

type | string | required

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

gateway | string | required

The unique gateway identifier that directs the customer straight to the payment method.
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

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

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.

Response

amount_refunded | integer

The amount refunded to the customer.

costs | object

See costs (object).

created | string

The timestamp for when the order was created.

custom_info | object

See custom_info (object).

status | string

The order status.

transaction_id | integer

MultiSafepay’s identifier for the transaction (also known as the PSP ID).

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

cancel_url | string

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

POST - /orders

{
  "type":"redirect",
  "order_id":"my-order-id-1",
  "gateway":"ALIPAY",
  "currency":"EUR",
  "amount":1000,
  "description":"Test order description",
  "payment_options":{
    "notification_url":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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":[
      {
        "transaction_id":123456789,
        "amount":1000,
        "description":"",
        "type":"SYSTEM"
      }
    ],
    "payment_methods":[
      {
        "account_id":"",
        "amount":1000,
        "currency":"EUR",
        "description":"Test order description",
        "payment_description":"ALIPAY",
        "status":"initialized",
        "type":"ALIPAY"
      }
    ],
    "payment_url":"https://excashier.alipay.com/standard/auth.htm?auth_order_id=exc_5fc2c0045b9b455f87fedd6d7f41f021"
  }
}

Alipay

See also Payment methods – Alipay.

Alipay - redirect

Parameters

type | string | required

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

order_id | string | required

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

gateway | string | required

The unique gateway identifier to direct the customer straight to the payment method.
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).

Response

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

Alipay - direct

Parameters

type | string | required

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

order_id | string | required

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

gateway | string | required

The unique gateway identifier to direct the customer straight to the payment method.
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

Value: false.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

Response

transaction_id | integer

MultiSafepay’s identifier for the transaction (also known as the PSP ID).

created | string

The timestamp for when the order was created.

items | object

See items (object).

amount_refunded | integer

The amount refunded to the customer.

status | string

The order status.

financial_status | string

The transaction status of the order.

reason | string

fastcheckout | string

Value: NO.

modified | string

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

payment_details | object

See payment_details (object).

costs | object

See costs (object).

payment_methods | object

See payment_methods (object).

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

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":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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":"https://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

See also Payment methods – 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.
Value: redirect.

order_id | string | required

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

gateway | string | required

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

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

Value: false.

payment_options | object | required

See payment_options (object).

Response

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

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

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

order_id | string | required

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

gateway | string | required

For Apple Pay payments, use APPLEPAY.

currency | string | required

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

amount | integer | required

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

description | string | required

A text which will be shown with the order in your MultiSafepay account. Max 200 characters.

payment_options | object | required

See payment_options (object).

gateway_info | object

Contains:

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.

Response

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

POST - /orders

{
  "type":"redirect",
  "order_id":"my-order-id-1",
  "gateway":"MISTERCASH",
  "currency":"EUR",
  "amount":1000,
  "description":"Test order description",
  "payment_options":{
    "notification_url":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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.
Value: redirect.

order_id | string | required

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

gateway | string | required

The unique gateway identifier to direct the customer straight to the payment method.
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).

Response

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

POST - /orders

{
  "type":"redirect",
  "order_id":"my-order-id-1",
  "gateway":"MISTERCASH",
  "currency":"EUR",
  "amount":1000,
  "description":"Test order description",
  "payment_options":{
    "notification_url":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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.
Value: redirect.

order_id | string | required

Your unique identifier for the order.
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.
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

Contains:

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

Response

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

qr_url | string

The URL of the QR code.

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":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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":"https://www.example.com/client/notification?type=redirect&transactionid=apitool_13890779",
    "cancel_url":"https://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.
Value: redirect.

order_id | string | required

Your unique identifier for the order.
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.
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.

Response

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

Bank Transfer - direct

Parameters

type | string | required

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

order_id | string | required

Your unique identifier for the order.
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.
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.

Contains:
disable_send_email | boolean | optional

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.

Response

transaction_id | integer

MultiSafepay’s identifier for the transaction (also known as the PSP ID).

created | string

The timestamp for when the order was created.

var1 / var2 / var3 | string

Variables for storing additional data.

items | object

See items (object).

amount_refunded | integer

The amount refunded to the customer.

status | string

The order status.

financial_status | string

The transaction status of the order.

reason | string

fastcheckout | string

Value: NO.

modified | string

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

payment_details | object

See payment_details (object).

costs | object

See costs (object).

payment_methods | object

See payment_methods (object).

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 name of the account holder to be charged for the transaction.

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.

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

cancel_url | string

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

POST - /orders

{
  "type":"redirect",
  "order_id":"my-order-id-1",
  "gateway":"BELFIUS",
  "currency":"EUR",
  "amount":1000,
  "description":"Test order description",
  "payment_options":{
    "notification_url":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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,
        "amount":1000,
        "description":"Test order description",
        "type":"BELFIUS"
      }
    ],
    "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.
Value: redirect.

order_id | string | required

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

gateway | string | required

The unique gateway identifier to direct the customer straight to the payment method.
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).

Response

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

Belfius - direct

Parameters

type | string | required

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

order_id | string | required

Your unique identifier for the order.
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.
Value: BELFIUS.

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.

custom_info | object

See custom_info (object).

payment_options | object | required

See payment_options (object).

Response

transaction_id | integer

MultiSafepay’s identifier for the transaction (also known as the PSP ID).

created | string

The timestamp for when the order was created.

items | object

See items (object).

amount_refunded | integer

The amount refunded to the customer.

status | string

The order status.

financial_status | string

The transaction status of the order.

reason | string

fastcheckout | string

Value: NO.

modified | string

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

customer | object

See customer (object).

payment_details | object

See payment_details (object).

costs | object

See costs (object).

payment_methods | object

See payment_methods (object).

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

POST - /orders

{
  "type":"redirect",
  "order_id":"my-order-id-1",
  "gateway":"CBC",
  "currency":"EUR",
  "amount":1000,
  "description":"Test order description",
  "payment_options":{
    "notification_url":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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 Response

{
  "success":true,
  "data":{
    "amount":1000,
    "amount_refunded":0,
    "costs":[
      {
        "amount":500,
        "description":"",
        "transaction_id":123456789,
        "type":"SYSTEM"
      },
      {
        "transaction_id":123456789,
        "amount":500,
        "description":"",
        "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",
      "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/KBC

See also Payment methods – CBC/KBC.

Note: Ensure you provide the relevant gateway.

CBC/KBC - redirect

Parameters

type | string | required

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

order_id | string | required

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

gateway | string | required

The unique gateway identifier to direct the customer straight to the payment method.
Options: CBC, 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).

Response

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

CBC/KBC - direct

Parameters

type | string | required

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

order_id | string | required

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

gateway | string | required

The unique gateway identifier to direct the customer straight to the payment method.
Value: CBC, 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

Value: false.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

Response

amount_refunded | integer

The amount refunded to the customer.

created | string

The timestamp for when the order was created.

custom_info | object

See custom_info (object).

fastcheckout | string

Value: NO.

financial_status | string

The transaction status of the order.

items | object

See items (object).

modified | string

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

payment_details | object

See payment_details (object).

payment_methods | object

See payment_methods (object).

reason | string

related_transactions | object

Information about linked transactions.

status | string

The order status.

transaction_id | integer

MultiSafepay’s identifier for the transaction (also known as the PSP ID).

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

POST - /orders

{
  "type":"redirect",
  "order_id":"my-order-id-1",
  "gateway":"CREDITCARD",
  "currency":"EUR",
  "amount":1000,
  "description":"Test order description",
  "payment_options":{
    "notification_url":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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.

order_id | string | required

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

gateway | string | required

The gateway identifier.
Value: CREDITCARD.

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

Response

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

POST - /orders

{
  "type":"redirect",
  "order_id":"my-order-id-1",
  "gateway":"AMEX",
  "currency":"EUR",
  "amount":1000,
  "description":"Test order description",
  "payment_options":{
    "notification_url":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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.
Value: redirect.

order_id | string | required

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

gateway | string | required

The gateway identifier.
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.

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

Response

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

POST - /orders

{
  "type":"redirect",
  "order_id":"my-order-id-1",
  "gateway":"MASTERCARD",
  "currency":"EUR",
  "amount":1000,
  "description":"Test order description",
  "payment_options":{
    "notification_url":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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.
Value: redirect.

order_id | string | required

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

gateway | string | required

The gateway identifier.
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.

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

Response

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

POST - /orders

{
  "type":"redirect",
  "order_id":"my-order-id-1",
  "gateway":"VISA",
  "currency":"EUR",
  "amount":1000,
  "description":"Test order description",
  "payment_options":{
    "notification_url":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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.
Value: redirect.

order_id | string | required

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

gateway | string | required

The gateway identifier.
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.

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

Response

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

POST - /order

{
  "type":"redirect",
  "order_id":"my-order-id-1",
  "gateway":"VISA",
  "currency":"EUR",
  "amount":1000,
  "description":"Test order description",
  "payment_options":{
    "notification_url":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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.
Value: redirect.

order_id | string | required

Your unique identifier for the order.
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.

Response

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

POST - /orders

{
  "type":"redirect",
  "order_id":"my-order-id-1",
  "gateway":"DOTPAY",
  "currency":"EUR",
  "amount":1000,
  "description":"Test order description",
  "payment_options":{
    "notification_url":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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.

order_id | string | required

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

gateway | string | required

The unique gateway identifier for the payment method.
Value: DOTPAY.

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

Response

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

POST - / order

{
  "type": "redirect",
  "order_id": "my-order-id",
  "gateway": "EDENCO",
  "currency": "EUR",
  "amount": 100,
  "description": "Test order description",
  "manual": false,
  "payment_options": {
    "notification_url": "https://www.example.com/client/notification?type=notification",
    "redirect_url": "https://www.example.com/client/notification?type=redirect",
    "cancel_url": "https://www.example.com/client/notification?type=cancel",
    "settings": {
      "gateways": {
        "coupons": {
          "allow": [
            "EDENECO"
          ],
          "disabled": false
        }
      }
    }
  },
  "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"
  }
}

Edenred

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

Parameters

type | string | required

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

order_id | string | required

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

gateway | string | optional

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

Options:
EDENCOM = Ticket Compliments
EDENECO = Ticket EcoCheque
EDENRES = Ticket Restaurant
EDENSPORTS = Ticket Sport & Culture

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

Value: false.

payment_options | object | required

Specifies which vouchers to display to the customer.

For more information, see payment_options (object).

customer | object | required

See customer (object).

Response

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

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":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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"
  }
}

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":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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":"https://www.example.com/client/?action=notification&type=redirect&transactionid=2340676",
      "cancel_url":"https://www.example.com/client/?action=notification&type=cancel&transactionid=2340676"
    }
  }

E-Invoicing

See also Payment methods – E-Invoicing.

E-Invoicing - redirect

Parameters

type | string | required

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

gateway | string | required

The unique gateway identifier for the payment method.
Value: EINVOICE.

order_id | string | required

Your unique identifier for the order.
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

Value: false.

gateway_info | object

Contains:

email | string

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

checkout_options | object

The definitions for the VAT class.

E-Invoicing - direct

Parameters

type | string | required

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

gateway | string | required

The unique gateway identifier for the payment method.
Value: EINVOICE.

order_id | string | required

Your unique identifier for the order.
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

Value: false.

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.

payment_options | object | required

See payment_options (object).

shopping_cart | object

See shopping_cart.items (object).

checkout_options | object

The definitions for the VAT class.

Response

transaction_id | integer

MultiSafepay’s identifier for the transaction (also known as the PSP ID).

created | string

The timestamp for when the order was created.

amount_refunded | integer

The amount refunded to the customer.

status | string

The order status.

financial_status | string

The transaction status of the order.

reason | string

fastcheckout | string

Value: NO.

modified | string

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

customer | object

See customer (object).

payment_details | object

See payment_details (object).

shopping_cart.items | required

See shopping_cart.items object.

costs | object

See costs (object).

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

cancel_url | string

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

POST - /orders

{
  "type":"redirect",
  "order_id":"my-order-id-1",
  "gateway":"EPS",
  "currency":"EUR",
  "amount":1000,
  "description":"Test order description",
  "payment_options":{
    "notification_url":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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.

order_id | string | required

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

gateway | string | required

The unique gateway identifier for the payment method.
Value: EPS.

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

Response

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

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":"https://www.example.com/client/json-live/notification?type=notification",
    "redirect_url":"https://www.example.comclient/json-live/notification?type=redirect",
    "cancel_url":"https://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.

order_id | string | required

Your unique identifier for the order.
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.
Note: We only preselect the gift card supplied in the gateway.

Options:

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

Value: false.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

Response

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

POST - /orders

{
  "type":"redirect",
  "order_id":"my-order-id-1",
  "gateway":"GIROPAY",
  "currency":"EUR",
  "amount":1000,
  "description":"Test order description",
  "payment_options":{
    "notification_url":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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.

order_id | string | required

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

gateway | string | required

The unique gateway identifier for the payment method.
Value: GIROPAY.

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

Response

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

POST - /orders

{
  "type":"redirect",
  "order_id":"my-order-id-1",
  "gateway":"IDEAL",
  "currency":"EUR",
  "amount":1000,
  "description":"Test order description",
  "payment_options":{
    "notification_url":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://www.example.com/client/notification?type=cancel",
    "close_window":true
  }
}

JSON response

{
  "success":true,
  "data":{
    "amount":1000,
    "amount_refunded":0,
    "costs":[
      {
        "transaction_id":123456789,
        "amount":1000,
        "description":"",
        "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.
Value: redirect.

order_id | string | required

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

gateway | string | required

The unique gateway identifier for the payment method.
Value: IDEAL.

currency | string | required

The currency for the payment.
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).

Response

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

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.
Value: direct.

order_id | string | required

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

currency | string | required

The currency for the payment.
Value: EUR.

amount | integer | required

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

gateway | string | required

The unique gateway identifier for the payment method.
Options: iDEAL.

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.

custom_info | object

See custom_info (object).

gateway_info | object | required

Contains:

issuer_id | integer | required

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

payment_options | object | required

See payment_options (object).

Response

amount_refunded | integer

The amount refunded to the customer.

costs | object

See costs (object).

created | string

The timestamp for when the order was created.

customer | object

See customer (object).

fastcheckout | string

Value: NO.

financial_status | string

The transaction status of the order.

items | object

See items (object).

modified | string

The timestamp when the order was last modified.

payment_details | object

See payment_details (object).

payment_methods | object

See payment_methods (object).

reason | string

related_transactions | object

Information about linked transactions.

status | string

The order status.

transaction_id | integer

MultiSafepay’s identifier for the transaction (also known as the PSP ID).

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

POST - /orders

{
  "type":"redirect",
  "order_id":"my-order-id-1",
  "gateway":"iDEALQR",
  "currency":"EUR",
  "amount":1000,
  "description":"Test order description",
  "payment_options":{
    "notification_url":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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.
Value: redirect.

order_id | string | required

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

gateway | string | required

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

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:

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.

customer | object | required

See customer (object).

Response

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

qr_url | string

The URL of the QR code.

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":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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"
  }
}

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":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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"
  }
}

in3

See also Payment methods – in3.

in3 - redirect

Parameters

type | string | required

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

gateway | string | required

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

order_id | string | required

Your unique identifier for the order.
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

Value: false.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

delivery | object

See delivery (object).

gateway_info | object

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.

shopping_cart | object

See shopping_cart.items (object).

checkout_options | object

The definitions for the VAT class.

Response

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

in3 - direct

Parameters

type | string | required

The payment flow for the checkout process.
Value: 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 | string | required

Your unique identifier for the order.
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

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.

Response

amount_refunded | integer

The amount refunded to the customer.

costs | object

See costs (object).

created | string

The timestamp for when the order was created.

custom_info | object

See custom_info (object).

fastcheckout | string

Value: NO.

modified | string

The timestamp when the order was last modified.

payment_details | object

See payment_details (object).

payment_methods | object

See payment_methods (object).

reason | string

related_transactions | object

Information about linked transactions.

status | string

The order status.

transaction_id | integer

MultiSafepay’s identifier for the transaction (also known as the PSP ID).

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

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":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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"
  }
}

POST - /orders

{
  "type":"direct",
  "order_id":"my-order-id-1",
  "gateway":"INGHOME",
  "currency":"EUR",
  "amount":1000,
  "description":"Test order description",
  "payment_options":{
    "notification_url":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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,
        "amount":1000,
        "description":"",
        "type":"SYSTEM"
      }
    ],
    "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"
  }
}

ING Home’Pay

See also Payment methods – ING Home’Pay.

ING Home’Pay - redirect

Parameters

type | string | required

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

order_id | string | required

Your unique identifier for the order.
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.
Value: INGHOME.

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.

custom_info | object

See custom_info (object).

payment_options | object | required

See payment_options (object).

Response

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

ING Home’Pay - direct

Parameters

type | string | required

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

order_id | string | required

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

gateway | string | required

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

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

Response

transaction_id | integer

MultiSafepay’s identifier for the transaction (also known as the PSP ID).

created | string

The timestamp for when the order was created.

items | object

See items (object).

amount_refunded | integer

The amount refunded to the customer.

status | string

The order status.

financial_status | string

The transaction status of the order.

reason | string

fastcheckout | string

Value: NO.

modified | string

The timestamp when the order was last modified.

payment_details | object

See payment_details (object).

costs | object

See costs (object).

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

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":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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":"https://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":"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"
  },
  "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.
Value: redirect.

gateway | string | required

The unique gateway identifier for the payment method.
To retrieve gateway IDs, see Gateways.
Value: KLARNA.

order_id | string | required

Your unique identifier for the order.
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

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.

Response

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

POST - /orders

{
  "type":"redirect",
  "order_id":"my-order-id-1",
  "gateway":"MAESTRO",
  "currency":"EUR",
  "amount":1000,
  "description":"Test order description",
  "payment_options":{
    "notification_url":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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.
Value: redirect.

order_id | string | required

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

gateway | string | required

The gateway identifier.
Value: MAESTRO.

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

Response

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

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": "https://www.example.com/client/notification?type=notification",
        "redirect_url": "https://www.example.com/client/notification?type=redirect",
        "cancel_url": "https://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":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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":[
      {
        "transaction_id":2045938,
        "amount":500,
        "description":"",
        "type":"SYSTEM"
      },
      {
        "amount":500,
        "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.
Value: redirect.

gateway | string | required

The unique gateway identifier for the payment method.
Value: PAYAFTER.

order_id | string | required

Your unique identifier for the order.
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

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.

bank_account | 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).

shopping_cart | object

See shopping_cart.items (object).

checkout_options | object

The definitions for the VAT class.

Response

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

Pay After Delivery - direct

Parameters

type | string | required

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

gateway | string | required

The unique gateway identifier for the payment method.
Value: PAYAFTER.

order_id | string | required

Your unique identifier for the order.
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

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.

bank_account | 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).

shopping_cart | object

See shopping_cart.items (object).

checkout_options | object

The definitions for the VAT class.

Response

amount_refunded | integer

The amount refunded to the customer.

costs | object

See costs (object).

created | string

The timestamp for when the order was created.

custom_info | object

See custom_info (object).

status | string

The order status.

transaction_id | integer

MultiSafepay’s identifier for the transaction (also known as the PSP ID).

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

cancel_url | string

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

POST - /orders

{
  "type":"redirect",
  "order_id":"my-order-id-1",
  "gateway":"PAYPAL",
  "currency":"EUR",
  "amount":1000,
  "description":"Test order description",
  "payment_options":{
    "notification_url":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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.
Value: redirect.

order_id | string | required

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

gateway | string | required

The unique gateway identifier for the payment method.
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.

Response

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

PayPal - direct

Parameters

type | string | required

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

order_id | string | required

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

gateway | string | required

The unique gateway identifier for the payment method.
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.

manual | string | required

Value: false.

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.

Response

amount_refunded | integer

The amount refunded to the customer.

costs | object

See costs (object).

created | string

The timestamp for when the order was created.

custom_info | object

See custom_info (object).

fastcheckout | string

Value: NO.

financial_status | string

The transaction status of the order.

items | object

See items (object).

modified | string

The timestamp when the order was last modified.

payment_details | object

See payment_details (object).

payment_methods | object

See payment_methods (object).

reason | string

related_transactions | object

Information about linked transactions.

status | string

The order status.

transaction_id | integer

MultiSafepay’s identifier for the transaction (also known as the PSP ID).

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

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":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://www.example.com/client/notification?type=cancel",
    "close_window":true
  }
}

JSON response

{
  "success":true,
  "data":{
    "amount":9743,
    "amount_refunded":0,
    "costs":[
      {
        "transaction_id":123456789,
        "amount":50,
        "description":"",
        "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.
Value: redirect.

order_id | string | required

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

gateway | string | required

The unique gateway identifier to direct the customer straight to the payment method.
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.

manual | string | required

Value: false.

payment_options | object | required

See payment_options (object).

Response

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

Request to Pay - direct

type | string | required

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

order_id | string | required

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

gateway | string | required

The unique gateway identifier to direct the customer straight to the payment method.
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.

manual | string | required

Value: false.

payment_options | object | required

See payment_options (object).

Response

amount_refunded | integer

The amount refunded to the customer.

costs | object

See costs (object).

created | string

The timestamp for when the order was created.

custom_info | object

See custom_info (object).

customer | object

See customer (object).

fastcheckout | string

Value: NO.

financial_status | string

The transaction status of the order.

items | object

See items (object).

modified | string

The timestamp when the order was last modified.

payment_details | object

See payment_details (object).

reason | string

related_transactions | object

Information about linked transactions.

status | string

The order status.

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

POST - /orders

{
  "type":"direct",
  "order_id":"my-order-id-1",
  "gateway":"SANTANDER",
  "currency":"EUR",
  "amount":50000,
  "description":"Test order description",
  "payment_options":{
    "notification_url":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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":"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"
  },
  "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,
        "amount":0.49,
        "description":"Cost description",
        "type":"SYSTEM"
      }
    ],
    "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.
Value: direct.

order_id | string | required

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

gateway | string | required

Valuegateway ID to direct the customer straight to the payment method.
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.

Response

transaction_id | integer

MultiSafepay’s identifier for the transaction (also known as the PSP ID).

created | string

The timestamp for when the order was created.

var1 / var2 / var3 | string

Variables for storing additional data.

items | object

See items (object).

amount_refunded | integer

The amount refunded to the customer.

status | string

The order status.

financial_status | string

The transaction status of the order.

reason | string

fastcheckout | string

Value: NO.

modified | string

The timestamp when the order was last modified.

payment_details | object

See payment_details (object).

costs | object

See costs (object).

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

POST - /orders

{
  "type":"redirect",
  "order_id":"my-order-id-1",
  "gateway":"DIRDEB",
  "currency":"EUR",
  "amount":1000,
  "description":"Test order description",
  "payment_options":{
    "notification_url":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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,
        "amount":0.0,
        "description":"0.0 For SEPA Direct Debit Transactions",
        "type":"SYSTEM"
      }
    ],
    "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.
Value: redirect.

order_id | string | required

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

gateway | string | required

The unique gateway identifier for the payment method.
Value: IDEAL.

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.

customer | object | required

See customer (object).

Response

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

SEPA Direct Debit - direct

Parameters

type | string | required

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

order_id | string | required

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

gateway | string | required

The unique gateway identifier for the payment method.
Value: DIRDEB.

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.

Response

transaction_id | integer

MultiSafepay’s identifier for the transaction (also known as the PSP ID).

created | string

The timestamp for when the order was created.

items | object

See items (object).

amount_refunded | integer

The amount refunded to the customer.

status | string

The order status.

financial_status | string

The transaction status of the order.

reason | string

fastcheckout | string

Value: NO.

modified | string

The timestamp when the order was last modified.

payment_details | object

See payment_details (object).

costs | object

See costs (object).

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

cancel_url | string

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

POST - /orders

{
  "type":"redirect",
  "order_id":"my-order-id-1",
  "gateway":"DIRECTBANK",
  "currency":"EUR",
  "amount":1000,
  "description":"Test order description",
  "payment_options":{
    "notification_url":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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":[
      {
        "transaction_id":123456789,
        "amount":743,
        "description":"",
        "type":"SYSTEM"
      },
      {
        "amount":900,
        "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":"https://www.example.com/client/notification?type=cancel"
  }
}

Sofort

See also Payment methods – Sofort.

Sofort - redirect

Parameters

type | string | required

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

order_id | string | required

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

gateway | string | required

The unique gateway identifier for the payment method.
Value: DIRECTBANK.

currency | string | required

The currency you want the customer to pay in.
Format: ISO-4217 currency codes.
For supported currencies, see Sofort product rules.

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

Response

amount_refunded | integer

The amount refunded to the customer.

costs | object

See costs (object).

created | string

The timestamp for when the order was created.

custom_info | object

See custom_info (object).

fastcheckout | string

Value: NO.

financial_status | string

The transaction status of the order.

items | object

See items (object).

modified | string

The timestamp when the order was last modified.

payment_details | object

See payment_details (object).

payment_methods | object

See payment_methods (object).

reason | string

related_transactions | object

Information about linked transactions.

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

cancel_url | string

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

Sofort - direct

Parameters

type | string | required

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

order_id | string | required

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

gateway | string | required

The unique gateway identifier for the payment method.
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.

manual | string | required

Value: false.

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

Response

amount_refunded | integer

The amount refunded to the customer.

costs | object

See costs (object).

created | string

The timestamp for when the order was created.

custom_info | object

See custom_info (object).

fastcheckout | string

Whether this is a FastCheckout transaction. Options: YES, NO.

financial_status | string

The transaction status of the order.

items | object

See items (object).

modified | string

The timestamp when the order was last modified.

payment_details | object

See payment_details (object).

payment_methods | object

See payment_methods (object).

reason | string

related_transactions | object

Information about linked transactions.

status | string

The order status.

transaction_id | integer

MultiSafepay’s identifier for the transaction (also known as the PSP ID).

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

cancel_url | string

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

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":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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.
Value: redirect.

order_id | string | required

Your unique identifier for the order.
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.
Value: TRUSTLY.

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.

custom_info | object

See custom_info (object).

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

Response

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

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":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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.
Value: redirect.

order_id | string | required

Your unique identifier for the order.
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.
Value: TRUSTPAY.

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.

custom_info | object

See custom_info (object).

payment_options | object | required

See payment_options (object).

customer | object | required

See customer (object).

Response

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

POST - /orders

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

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":"WECHAT",
  "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": {
    "amount": 1000,
    "amount_refunded": 0,
    "costs": [
      {
        "amount": 0.3,
        "description": "Test order description",
        "transaction_id": 123456789,
        "type": "SYSTEM"
      }
    ],
    "created": "2021-09-16T14:39:50",
    "currency": "EUR",
    "custom_info": {
      "custom_1": null,
      "custom_2": null,
      "custom_3": null
    },
    "customer": {
      "address1": "Kraanspoor",
      "address2": null,
      "city": "Amsterdam",
      "country": "NL",
      "country_name": null,
      "email": "[email protected]",
      "first_name": "Simon",
      "house_number": "39C",
      "last_name": "Smit",
      "locale": "cn_CN",
      "phone1": "0208500500",
      "phone2": "",
      "state": null,
      "zip_code": "1033SC"
    },
    "description": "product description",
    "fastcheckout": "NO",
    "financial_status": "initialized",
    "items": null,
    "modified": "2021-09-16T14:39:50",
    "order_id": "my-order-id-1",
    "payment_details": {
      "account_holder_name": 123456789,
      "account_id": "wx<string>",
      "external_transaction_id": "wx<string>",
      "recurring_flow": null,
      "recurring_id": null,
      "recurring_model": null,
      "type": "WECHAT"
    },
    "payment_methods": [
      {
        "account_holder_name": 123456789,
        "account_id": "wx<string>",
        "amount": 1000,
        "currency": "EUR",
        "description": "product description",
        "external_transaction_id": "wx<string>",
        "payment_description": "WeChat Pay",
        "status": "initialized",
        "type": "WECHAT"
      }
    ],
    "qr_url": "weixin://wxpay/bizpayurl?pr=<string>",
    "reason": "",
    "reason_code": "",
    "related_transactions": null,
    "status": "initialized",
    "transaction_id": 123456789,
    "var1": null,
    "var2": null,
    "var3": null,
    "payment_url": "http://www.example.com/client/notification?type=redirect&transactionid=my-order-id-1",
    "cancel_url": "http://www.example.com/client/notification?type=cancel"
  }
}

WeChat Pay

See also Payment methods – WeChat Pay.

WeChat Pay - redirect

Parameters

type | string | required

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

order_id | string | required

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

gateway | string | required

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

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

Response

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

WeChat Pay - direct

Parameters

type | string | required

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

order_id | string | required

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

gateway | string | required

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

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

Response

amount_refunded | integer

The amount refunded to the customer.

costs | object

See costs (object).

created | string

The timestamp for when the order was created.

custom_info | object

See custom_info (object).

customer | object

See customer (object).

description | string

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.

fastcheckout | string

Fixed value: NO.

financial_status | string

The transaction status of the order.

modified | string

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

items | object

See items (object).

modified | string

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

order_id | string | required

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

payment_details | object

See payment_details (object).

payment_methods | object

See payment_methods (object).

qr_url | string

The URL of the QR code.

reason | string

related_transactions | string

Information about linked transactions.

status | string

The order status.

transaction_id | integer

MultiSafepay’s identifier for the transaction (also known as the PSP ID).

var1 / var2 / var3 | string

Variables for storing additional data.

payment_url | string

The URL of the page where the customer is redirected from your checkout to complete payment, which may be hosted by MultiSafepay, the issuer, or the payment method.

cancel_url | string The page the customer is redirected to if the payment fails.

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.

For authentication, use your account API key.

Parameters

affiliated_id | query parameter | required

The account ID of the affiliated account.

Responses

account_id | string

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

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 / var2 / var3 | string | optional

Variables for storing additional data.

Response

costs | object

See costs (object).

created | string

The timestamp for when the order was created.

currency | string

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

financial_status | string

The transaction status of the order.

payment_method | string

The payment method.

site_id | string

The website identifier.
See Site ID, API key, and secure code.

status | string

The order status.

transaction_id | integer

MultiSafepay’s identifier for the transaction (also known as the PSP ID).

type | string

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

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

See also Making 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 / var2 / var3 | string | optional

Variables for storing additional data.

Response

costs | object

See costs (object).

created | string

The timestamp for when the order was created.

financial_status | string

The transaction status of the order.

order_id | string

Your unique identifier for the charge.

payment_method | string

The payment method.

site_id | string

The website identifier.
See Site ID, API key, and secure code.

status | string

The order status.

transaction_id | integer

MultiSafepay’s identifier for the transaction (also known as the PSP ID).

type | string

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

bankaccount | object

Contains:

currency | string | required

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

holder_name | string

The card holder’s name.

iban | string

The customer’s international bank account number (IBAN).

id | string

The balance ID.

Other requests

Manage tokens

To process recurring payments, MultiSafepay stores payment details as encrypted tokens for subsequent payments, e.g. subscriptions.

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

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

JSON response

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

Get token details

Retreive information about a specific token.

Parameter

token | string | required

The unique token linked to the customer reference.

Response

code | string

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

display | string

How the customer’s credit card number is displayed.

name_holder | string

The card holder’s name.

expiry_date | integer

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

expired | boolean

Whether the card has expired.

last4 | string

The last 4 digits of the credit card number.

model | string

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

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":1234,
        "expired":0,
        "last4":1111,
        "recurring_model":"cardOnFile"
      },
      {
        "token":"GVXjq3432o4",
        "code":"VISA",
        "display":"1234 5678 9101 2345",
        "bin":411111,
        "name_holder":"WebcashierE2E",
        "expiry_date":1234,
        "expired":0,
        "last4":2222,
        "recurring_model":"unscheduled"
      }
    ]
  }
}

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

Response

tokens | object

Contains:

code | string

The unique identifier of the payment gateway.

display | string

How the customer’s credit card number is displayed.

name_holder | string

The card holder’s name.

expiry_date | integer

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

expired | boolean

Whether the card has expired.

last4 | string

The last 4 digits of the credit card number.

recurring_model | string

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

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.

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.

Make a DELETE 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

token | string | required

The unique token identifier linked to the customer reference.

Response

removed | boolean

Whether the token was successfully deleted.

POST - /json/padprechecks

{
  "type":"checkout",
  "gateway":"PAYAFTER",
  "order_id":"my-order-id-1",
  "currency":"EUR",
  "amount":9000,
  "description":"Order description",
  "payment_options":{
    "notification_url":"https://www.example.com/client/notification?type=notification",
    "redirect_url":"https://www.example.com/client/notification?type=redirect",
    "cancel_url":"https://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":"https://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='https://example.com' target='_blank'>algemene voorwaarden</a>"
          },
          {
            "en":"I accept the <a href='https://example.com' 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":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.

gateway | string | required

The unique gateway identifier for the payment method.
To retrieve gateway IDs, see Gateways.

order_id | string | required

Your unique identifier for the order.
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 | required

See delivery (object).

shopping_cart | object | required – or use items

See shopping_cart.items (object).

checkout_options | object

The definitions for the VAT class.

GET - /transactions

JSON response

{
  "amount":0,
  "completed":"string",
  "costs":[
    null
  ],
  "created":"string",
  "currency":"string",
  "debit_credit":"D_C",
  "description":"string",
  "financial_status":"string",
  "invoice_id":"string",
  "order_id":"string",
  "payment_method":"string",
  "site_id":0,
  "status":"string",
  "transaction_id":0,
  "type":"string",
  "var1":"string",
  "var2":"string",
  "var3":"string"
}

Retrieve transactions

Get details about transactions in your account.

For use cases and sample requests, see Transactions endpoint.

Requests retrieve an array of all transactions under your account. See also Pagination.

API key

Set your API key to the Authorization header value:

curl -X GET "https://testapi.multisafepay.com/v1/json/transactions" --header "Content-Type: application/json" --header "api_key: <your-account-api-key>"

Note: Use your test API key when making requests to the test API URL.

Parameters

Use the following optional parameters to filter the returned transactions:

Note: For timestamps:

  • All timestamps are in CET/CEST timezone.
  • Multiple formats are supported and automatically detected:

site_id | integer (single value or array of values)

Returns transactions for a specific website in your account.
Default: Returns transactions for all sites under your account.
Format: 12345

created_from | string

Timestamp. Returns transactions created on or after the specified date.

created_until | string

Timestamp. Returns transactions created before but not on the specified date.

completed_from | string

Timestamp. Returns transactions completed on or before the specified date.

completed_until | string

Timestamp. Returns transactions completed before but not on the specified date.

financial_status | string (single value or array of values)

Returns transactions with the specified transaction status.
Options: completed, created, declined, error, expired, initialized, manual, new, refunded, reserved, uncleared, void.

status | string (single value or array of values)

Returns transactions with the specified order status.
Options: completed, initialized, uncleared, declined, cancelled, void, expired, refunded, partial_refunded, reserved, chargeback, shipped.

payment_method | string (single value or array of values)

Returns transactions with the specified payment method.
Format: See Retrieve all gateways, e.g. VISA.

type | string (single value or array of values)

Returns transactions of the specified type.
Options: admin_fee, affiliate_payout, automatic_payout, chargeback, coupon, currency_conversion, deposit, fastcheckout, monthly_fee, payment, refund, reserve_chargeback, signup_fee.

limit | integer

Specifies the maximum number of results to return per page.
Default: 100.

after | string

Use the after cursor to request the next page of paginated results.
Format: cursor, e.g. ZD1ftlaZLHQ90EQCeQ.

before | string

Use the before cursor to request the previous page of paginated results.
Format: cursor, e.g. ZD1gIU-ZLPQ9AEX73Q.

GET - /categories

JSON response

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

Retrieve website categories

Retrieves a list of website categories.

Response

code | string

The unique identifier of the payment gateway.

description | string

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

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": "https://www.example.com/client/notification?type=notification",
    "redirect_url": "https://www.example.com/client/notification?type=redirect",
    "cancel_url": "https://www.example.com/client/notification?type=cancel",
    "settings": {
      "gateways": {
        "coupons": {
          "allow": [
            "EDENECO"
          ],
          "disabled": false
        }
      }
    }
  }
}

JSON response

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

Specify vouchers

Specify which vouchers are displayed as options to the customer for the transaction.

Parameters

Use the following optional parameters in the payment_options (object) to specify which vouchers to display.

allow | array of strings | optional

An array specifying the vouchers to display to the customer.
If empty, no vouchers display.
If not included, then all activated vouchers display.

Options:
Baby Cadeaubon= BABYCAD
Beautyandwellness= BEAUTYWELL
Bloemencadeaukaart= BLOEMENCAD
Boekenbon= BOEKENBON
Degrotespeelgoedwinkel= DEGROTESPL
Edenred Ticket Compliments= EDENCOM
Edenred Ticket EcoCheque= EDENCO
Edenred Ticket Restaurant= EDENRES
Edenred Ticket Sport & Culture= EDENSPORTS
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

disabled | boolean | optional

Disables displaying all vouchers to the customer.

If set to true, the allow parameter is ignored.

Options: true, false.

Objects

This section lists the attributes of large, commonly used objects in requests. 

{
  "costs":[
    {
      "transaction_id":123456789,
      "amount":0.19,
      "description":"Refund order 258655825 for TEST TEST",
      "type":"internal",
      "created":"2019-03-01T16:14:02",
      "status":"completed"
    }
  ]
}

costs (object)

May contain:

transaction_id | integer

MultiSafepay’s identifier for the transaction (also known as the PSP ID).

amount | integer |

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

description | string |

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.

type | string

Options: SYSTEM, internal.

created | string

The timestamp for when the order was created.

currency | string

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

status | string

The order status.

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

customer (object)

The customer’s personal information.

Contains:

Parameters

locale | string | required

Localizes the payment page with the customer’s language, region, and available payment methods.
For more information, see Locale parameter.
Format: ab_CD with ISO 639 language codes and ISO 3166 country codes.
Default: en_US (American English).

ip_address | string | required / recommended

The customer’s IP address.
Required for pay later methods and credit cards as part of our fraud check, optional but recommended for other payment methods.
If empty or incorrect (e.g. your IP address instead of the customer’s) when required, the transaction status may be Uncleared, or even Declined.

forwarded_ip | string | required

The X-Forwarded-For header of the customer object when using a proxy.
To retrieve the customer’s IP address:

  • If there is a proxy, use forwarded_ip.
  • Otherwise, use ip_address.

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 recurring payments transactions: required

See Create recurring payments orders.

{
  "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 shipping the order.

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_details":{
    "account_holder_name":null,
    "account_id":"NL87ABNA0000000001",
    "external_transaction_id":null,
    "recurring_id":null,
    "recurring_model":null,
    "type":"DIRECTBANK"
  }
}

payment details (object)

May contain:

Parameters

account_holder_name | string

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

account_id | string

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

recurring_id | string

The unique identifier for the recurring payment.

recurring_model | string

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

type | string

The payment gateway.

account_bic | string

The bank identification code (BIC) of the customer’s bank.

issuer_id | integer

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

external_transaction_id | string

The order reference number from a third party, e.g. the payment method.

{
  "payment_methods":[
    {
      "account_id":10071970,
      "amount":9743,
      "currency":"EUR",
      "description":"Test order description",
      "payment_description":"SOFORT Banking",
      "status":"initialized",
      "type":"DIRECTBANK"
    }
  ]
}

payment methods (object)

May contain:

Parameters

account_id | string

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

amount | integer

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

currency | string

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

description | string

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

The payment method.

status | string

The order status.

external_transaction_id | string

The order reference number from a third party, e.g. the payment method.

account_holder_name | string

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

type | string

The payment gateway.

card_expiry_date | string

The expiry date of the credit card.

last4 | string

The last 4 digits of the credit card number.

{
  "payment_options": {
    "notification_url": "https://www.example.com/client/notification?type=notification",
    "redirect_url": "https://www.example.com/client/notification?type=redirect",
    "cancel_url": "https://www.example.com/client/notification?type=cancel",
    "notification_method": "POST",
    "close_window": true,
    "settings": {
      "gateways": {
        "coupons": {
          "allow": [
            "EDENECO"
          ],
          "disabled": false
        }
      }
    }
  }
}

payment options (object)

URLs for sending notifications to, or redirecting customers to.

Contains:

Parameters

notification_url | string | required

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

redirect_url | string | required

Your success/thank you page, where the customer is redirected after completing payment.
For more information, see Redirect URL.

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

settings | object | optional

Configures options for the payment.

Contains:

  • gateways | object | optional

Contains:

  • coupons | object | optional

    Contains:

    • allow | array of strings | optional

    An array specifying the vouchers to display to the customer.
    If empty, no vouchers display.
    If not included, then all activated vouchers display.
    See specify vouchers.

    • disable | boolean | optional

    Disables displaying all vouchers to the customer.
    If set to true, the allow parameter is ignored.

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

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

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.

{
  "var1":null,
  "var2":null,
  "var3":null,
}

variables

var1 / var2 / var3 | string | optional

Variables for storing additional data.

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.