Authentication

When using our POS endpoints, always use the API key of your device's terminal group.

API endpoints

The procedure to create an order with your terminal depends on the solution have implemented in your flow. These are:

Cloud POS payments

To start processing payment with cloud mode, just you first enable this feature from the MultiSafepay app. For more information, see how to enable cloud mode, under Payment settings.

See our recipe to learn how to process cloud payments.

  curl --request POST \
   --url 'https://testapi.multisafepay.com/v1/json/orders?api_key=YOUR_GROUP_API_KEY' \
   --header 'Accept: application/json' \
   --header 'Content-Type: application/json'
   --data '
{
"type": "redirect",
"order_id": "test-663",
"gateway": "",
"currency": "EUR",
"amount": 100,
"description": "Test Order Kiosk Description",
"payment_options": {
    "notification_url": "https://www.example.com/event/notifications",
  "notification_method": "POST"
  },
"customer": {
    "locale": "nl_NL",
    "phone": "0612345678",
    "email": "[email protected]"
},
"gateway_info": {
        "terminal_id": "000000MB"
}
}

     {
         "success":true,
         "data": {
             "order_id": "test-663",
             "payment_url": "https://payv2.multisafepay.com/connect/216OZwLaVQwre3FUd7W3kfvQ0CcEedaOgGm/?lang=nl_NL", 
             "session_id": "243erLaVQwre3FUd7W3kfvQ0CcEedaOgGm", 
             "events_token": "eyJhbGciOitresfjNiJ9.yfdhwOjE2ODQ5MTc0NzcsImdydCI6WyJtYnVzOnNlc3Npb24ub3JkZXIiLCJtYnVzOnNlc3Npb24ucXIiXSwicGlkIjoiMjE2T1p3TGFWUXdyZTNGVWQ3VzNrZnZRMENjRWVkYU9nR20iLCJzdWIiOiJwciJ9.TDf4Kx0ihNBxKrHD1DtBVcjjA2qBqM9IfQXNX_iAlmk", 
             "events_stream_url": "https://api.dev.multisafepay.com/events/stream/"
        }

On-same device applications

App-to-app

Check our GitHub repository lo learn how to integrate our solution for your app.

Web-to-app

Check the instructions below to learn how to create payments using our Web-to-app solution.

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

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

Manual input

With Manual input, you can process payment directly from the MultiSafepay app. See SmartPOS features to learn more about customization.

Cancel an order

To cancel an order, make a Cancel transaction request. This requires the use of an order_id and a terminal group API key, which you can find at your MultiSafepay dashboard under Manage groups.

Insert 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

You can process refunds:

Via the API

See API reference – Refund order.

From your terminal

1. Open the MultiSafepay application from your terminal and go to Features.
2. Click History and select the relevant transaction.
3. Click Refund. Enter the desired amount you want to refund and click OK.
4. Click Confirm to finalize the transaction. The refund will be processed.
5. Click Close.

In your dashboard

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

Receipts

To can get a receipt:

Via the API

See API reference - Get receipt.

From your terminal

You can print receipts for payments and refunds using the built-in or external printer:

• Directly after completing a transaction, enabling the auto-print feature. See how to enable auto-print.
• From your transaction history list in your terminal's MultiSafepay application, under Settings > History, selecting the relevant transaction and clicking Refund.

Terminal management

You can manage your terminals:

Via de API

• Make a List terminals request to retrieve information about all terminals onboarded for your account.
• Make a List terminals by group request to retrieve information for a specific terminal group.

From your MultiSafepay dashboard

1. Log in to your MultiSafepay dashboard.
2. Go to Devices > Terminals.
3. Here, you can:
   1. Filter your terminals by group.
   2. Edit your terminal groups.
   3. Add new terminals.

Check the settings available in your MultiSafepay dashboard below.

Terminal groups

A terminal group is required for linking and activating a SmartPOS device. You can create a single group or multiple groups for segmentation. Each terminal group is assigned a unique API key and ID. All transactions processed by terminals within the same terminal group are consolidated under a single reconciliation history.

This functionality offers reconciliation, reporting and management for single and multiple terminal groups.

How to create a terminal group

To create a terminal group:

1. Sign in to your MultiSafepay dashboard.
2. Go to Devices > Terminals.
3. Click Manage groups.
4. Click + Add new group.
5. Insert a name for your group, and optionally, a logo to enable branding, and a Webhook URL to receive updates for your payments.
6. Click Create.

Your new terminal group will be added to the Manage groups list. A terminal group ID and an API key will be associated.

To view the ID and API key for a terminal group:

1. Sign in to your MultiSafepay dashboard.
2. Go to Devices > Terminals.
3. Click on Manage groups.
4. A list of all available terminal groups will be displayed, showing the ID and API key for each group.

How to edit a group

1. At Manage groups click the edit icon on the right side of the panel to edit the desired terminal group. Here, you can:

• Change the name of the terminal group.
• Change the logo by selecting a different image file.
• Change the webhook URL.

2. Click Save💾.

How to upload your logo

1. Go to your MultiSafepay dashboard .

2. Go to Settings > Files and upload the desired image file. The file must meet the following requirements:

   • Format: PNG
   • Resolution: 512x512 pixels

   You can upload multiple files at the same time.

3. Click Upload for single files or Upload all to upload all files.

Top of page

Updates

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

Make a Get order request to retrieve POS-specific details, such as the terminal_id or the tip.amount.

{
"success": true,
"data": {
"amount": 2,
"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",
"tip": {
"amount": 1
},
"transaction_id": 123412342341234,
"var1": null,
"var2": null,
"var3": null
}
}

You can also make a List transactions or a Get transaction request to retrieve transactions processed within a terminal group.

Testing

POS transactions cannot be simulated in our TEST environment. All testing must be conducted in your LIVE MultiSafepay account.