Authentication

When using our POS endpoints, always use the API key of your device's terminal group. You can retrieve your API key from your MultiSafepay dashboard under Manage groups.

How to create an order

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

Manual input

With Manual input, you can process payments directly from the MultiSafepay App. See Features to learn more about customization.

Manual order ID

You can use the Insert Order ID feature to enter a custom order_id using Manual input. To process payments where you can manually insert an Order ID:

1. Click Insert Order ID and insert the ID for your order.
2. Enter the amount you want to charge.
3. Click Pay to initiate the payment.

QR code payments

You can create a QR code to scan with your device to initiate a payment. To do this, first enable the insert Order ID feature in the MultiSafepay App.

To create a QR code:

1. Create a JSON containing that following parameters:

• order_id: The unique id of the order
• amount: Add the amount for your order
• description: Give your order a description

{
  "order_id":"your_order_id",
  "amount":100,
  "description":"Your order description",
}

2. Generate a QR code using the JSON as input.
3. Using Manual input, click Scan QR and scan your code. The amount will be displayed on the screen.
4. Click Pay to initiate the payment.

Cloud POS payments

To start processing payments using cloud mode, ensure that you 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

Before creating an order with the app-to-app flow, make sure you have followed the instructions and have correctly integrated our solution in our POS Android Integration guide.

Check the instructions below to learn how to create payments using our App-to-app solution:

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}

How to cancel an order

You can cancel an order:

Via your device

You can cancel payments on your device:

• Clicking Back from the navigation bar.
• Using the cancel button, which you must enable beforehand. For more information, see Cancel button
• Waiting until the payment expires, which takes 1 minute.

Via API

1. Make a Cancel transaction request.
2. Insert the order_id and the terminal group API key in the URL.
3. The order will be cancelled on your device.

Check the example below:

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

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

1. Open the MultiSafepay App from your device 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

You can retrieve receipt details:

Via the API

See API reference - Get receipt.

From your device

You can print receipts for payments and refunds using a built-in printer (if the device supports it), or an 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 MultiSafepay App, under Settings > History, selecting the relevant transaction and clicking Print.

Device management

You can manage your devices:

Via API

• Make a List terminals request to retrieve information about all devices 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 devices by group.
   2. Edit your terminal groups.
   3. Add new devices.

Check the settings available in your MultiSafepay dashboard below.

Terminal groups

A terminal group is required for linking and activating a 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.

You can edit your terminal group name, webhook, and customize branding by uploading your logo.

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 with it.

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. Under 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. See how to upload your logo.
• 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.

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.

Next step