⚠️
Note:
We currently offer this product in the following countries:

Netherlands

Belgium

As a partner, you can further connect accounts registered in the following countries:

Italy

Spain

If you are interested in our Point of Sale solutions, email [email protected]

Our SmartPOS solutions let you initiate payments through:

Manual input
Cloud POS payment
On-same device third-party applications
- Web application
- Native application

Manual input

To start processing payments manually:

Enter Amount due and select Pay.
The customer can either tap or insert their card to make the payment.
Once the payment is completed, a notification is displayed.

Cloud POS payment

With cloud POS payment, you can initiate payments from an external application.

This diagram shows a successful cloud-based POS payment flow. Click to magnify.

cloud-POS

⚠️ Note: Before you start initiating payments, you must ensure cloud mode is enabled - see SmartPOS features.

Create an order. See Recipe - Cloud POS payment .
Cancel an order. See cancellation.

To receive payments updates subscribe to Event notifications.

⚠️ Note: When using event notifications on POS terminals, you might encounter soft declines when processing payments. For more information, see Soft declines.

On-same device third-party applications

Web applications

Web applications let you initiate payments on-same devices from a browser to the payment app.

This diagram shows a successful web application payment flow. Click to magnify.

web-app-POS

Initiate payments

Before initiating web application payments, you need to create an order.

Example

curl -X POST \
"https://api.multisafepay.com/v1/json/orders?api_key={your-api-key}"
-d '{
  "type": "redirect",
  "order_id": "my_order_id",
  "gateway": "",
  "currency": "EUR",
  "amount": 10,
  "description": "Order Description",
  "payment_options": {
      "notification_url": "https://www.example.com/paymentnotification",
      "notification_method": "POST"
  }
}
'

Initiate a payment using the URL below:

msp://?amount={$amount}&order_id={$order_id}&callback={$callback_url}&printing=true&tipping=true&notification_url={$notification_url}

amount: the amount specified in EUR cents.
order_id: your unique identifier for order ID.
callback_url: this URL redirects the customer to receive payment status notifications.
Optionally, you can set notification_url to receive order payment updates notifications.
tipping: include a tip.
printing: activate printing function.

Payment status received can either be Completed or Cancelled.

Native applications

Native applications let you initiate payments on-same devices from app to payment app.

This diagram shows a successful native application payment flow. Click to magnify.

native-app-POS

Initiate payments

Before initiating native application payments, you need to create an order.

Example

curl -X POST \
"https://api.multisafepay.com/v1/json/orders?api_key={your-api-key}"
-d '
{
  "type": "redirect",
  "order_id": "my_order_id",
  "gateway": "",
  "currency": "EUR",
  "amount": 10,
  "description": "Order Description",
  "payment_options": {
      "notification_url": "https://www.example.com/paymentnotification",
      "notification_method": "POST"
  }
}
'

To initiate payments - see MultiSafepay Android POS integration .

# API features

In addition to the features mentioned in our API reference, there are POS-specific details you can retrieve via our API, including the Terminal ID that processed a transaction.

Example GET order

{
  "success": true,
  "data": {
    "amount": 1,
    "amount_refunded": 0,
    "completed": "2024-06-04T15:50:18",
    "costs": [
      {
        "amount": 2,
        "description": "2 For Visa Transactions",
        "transaction_id": 899813954,
        "type": "SYSTEM"
      },
      {
        "amount": 0.6,
        "description": "2.9 % For Visa CreditCards Transactions (min 60)",
        "transaction_id": 899813955,
        "type": "SYSTEM"
      }
    ],
    "created": "2024-06-04T15:50:17",
    "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": null,
      "first_name": null,
      "house_number": null,
      "last_name": null,
      "locale": "en_US",
      "phone1": null,
      "phone2": null,
      "state": null,
      "zip_code": null
    },
    "description": "12341234",
    "fastcheckout": "NO",
    "financial_status": "completed",
    "items": null,
    "modified": "2024-06-04T15:50:18",
    "order_id": "TestGetOrder123123",
    "payment_details": {
      "account_holder_name": "card holder",
      "account_id": null,
      "application_id": "a0000000031010",
      "authorization_code": "705151",
      "card_acceptor_id": "1001001",
      "card_acceptor_location": "Amsterdam",
      "card_acceptor_name": "TestMSP",
      "card_additional_response_data": {
        "sca_details": {}
      },
      "card_authentication_result": null,
      "card_entry_mode": "ICC_CONTACTLESS",
      "card_expiry_date": "3112",
      "card_funding": "D",
      "card_product": "F",
      "card_product_type": 1,
      "card_sequence_number": "0000",
      "card_verification_result": "2",
      "cardholder_verification_method": "FAILED",
      "cardholder_verification_result": "UNKNOWN",
      "emv": {
        "91": "ab1231231234"
      },
      "external_transaction_id": "12312312312",
      "issuer_bin": "123123",
      "issuer_country_code": "ES",
      "last4": "1234",
      "recurring_flow": null,
      "recurring_id": "1231213123",
      "recurring_model": null,
      "response_code": "00",
      "scheme_reference_id": "123123123123123",
      "terminal_id": "0000004d",
      "type": "VISA"
    },
    "payment_methods": [
      {
        "account_holder_name": "card holder",
        "amount": 1,
        "card_expiry_date": "3112",
        "currency": "EUR",
        "description": "12341234",
        "external_transaction_id": "123123412341234",
        "payment_description": "Visa",
        "status": "completed",
        "type": "VISA"
      }
    ],
    "reason": "Approved",
    "reason_code": "1000",
    "related_transactions": null,
    "status": "completed",
    "transaction_id": 123412342341234,
    "var1": null,
    "var2": null,
    "var3": null
  }
}

Handle notifications

The table below sets out options available for receiving updates on the payments.

POS Solutions	Required	Optional
Cloud POS payment	Subscribe to the event notifications.	Configure a webhook.
Web applications	Set `callback_url` in the link.	Set `notification_url` in the link to configure a webhook.
Native applications	Set `package_name` in your intent call.	Configure a webhook.

Soft declines

When using webhook notifications or event notifications , you might encounter soft declines. A soft decline occurs when an initial payment attempt is declined, requiring the customer to take further action, such as entering their PIN, often for larger amounts.

With a soft decline, you first receive a notification with an order status of declined. Once the customer completes the required verification (e.g., enters their PIN), you'll receive another notification. If successful, the order status will be completed. If the payment fails, the order status will be cancelled.

User guide

Cancellation

You can use two different request methods to cancel an order: POST or PATCH. Both methods require the use of an order_id and a group API key, which you can find at your MultiSafepay dashboard under Manage groups.

PATCH request

To cancel an order with a PATCH request, follow these instructions:

The status parameter (string) must be set to cancelled.
Set exclude_order (boolean) to true. This sets the outcome of the cancellation.

Example Request


curl --location --request PATCH \
     --url 'https://api.multisafepay.com/v1/json/orders/{order_id}/?api_key={your-api-key}' \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json'
     --data ' 
{
  "status": "cancelled",
  "exclude_order": true
}
'

Example Response


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

POST request

To cancel an order with a POST request, no additional parameters are required. Introduce the order_id and the API key in the URL.

Example request

curl -X POST 
"https://api.multisafepay.com/v1/json/orders/{order_id}/cancel?api_key={your-api-key}"

Example response

{
  "success": true,
  "data": {
    "costs": [],
    "created": "dateTtime",
    "custom_info": {
      "custom_1": null,
      "custom_2": null,
      "custom_3": null
    },
    "fastcheckout": "NO",
    "financial_status": null,
    "modified": "dateTtime",
    "payment_details": {},
    "payment_methods": null,
    "status": "cancelled"
    }
}

Refunds

How to process refunds

Via the API

See API reference – Refund order.

In your dashboard

Sign in to your MultiSafepay dashboard .
Go to Transactions > Transaction overview, and click the relevant transaction.
On the Transaction details page, click Refund order.
In the Reason / Description field, enter the reason for the refund or a description of what happened with the order, and then click Complete.
In the Comment field, enter any additional information.
In the Amount fields, enter the amount to refund.
Click Continue.
Review Refund confirmation, and then click Confirm.

Updates

Make a Get order request to get updates on a specific order.

Testing

You cannot test terminals in your MultiSafepay test account.

Top of page

⚠️Note:

Manual input

Cloud POS payment

On-same device third-party applications

Web applications

Initiate payments

Native applications

Initiate payments

Handle notifications

Soft declines

User guide

Cancellation

Refunds

Updates

Testing

⚠️
Note: