After completing your integration, use this guide to manage your MultiSafepay POS solution.

Learn how to cancel payments, process refunds, retrieve receipts, manage terminals and terminal groups, interpret payment statuses, and monitor transactions through the API, your terminal, or the MultiSafepay dashboard.

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 cancel an order

You can cancel an order:

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",
        "modified": "dateTtime",
        "financial_status": null,
        "payment_details": {},
        "payment_methods": null,
        "status": "cancelled"
        }
    }

Via your device

In the Payment screen, cancel an order using one of the following methods:

* Click **Back** in the navigation bar.
* Click the **cancel button**, which you must enable beforehand. For more information, see [Cancel button](/docs/features#/navigation).
* Wait until the payment expires (after 1 minute).

How to process a refund

You can process refunds:

Via API

See API reference – [Refund order](/reference/refundorder).

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

From your MultiSafepay 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 API

See API reference - [Get receipt](/reference/getreceipt).

Via 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](/docs/smartpos-features#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

Onboard a new device

• Make a create SmartPOS terminal request to onboard a new SmartPOS device for an existing terminal group.
• Make a create terminal request to onboard a new CTAP terminal for an existing terminal group.

Reconcile POS transactions

• Make a get transaction request to retrieve the details of a specific POS transaction for reconciliation.
• Make a list transactions request to retrieve transactions linked to a specific terminal group. Use the terminal.id parameter to filter transactions by terminal ID.

Manage your terminals

• Make a get terminals request to retrieve information about all devices onboarded for your account.
• 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:

• Filter your devices by group.
• Edit your terminal groups.
• 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 set up your logo.
• Change the webhook URL.

2. Click Save 💾.

How to set up your logo for Cloud mode

Logos can be added to your device to customize branding when using Cloud mode. The logo must be uploaded to your MultiSafepay dashboard, and correctly selected from the terminal group settings.

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

  💡

  Tip! You can upload multiple files at the same time.

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

Once your logo has been uploaded:

1. Go to Configuration > Point of sale > Terminals
2. Click Manage groups to access the list of terminal groups
3. Click Edit. Under Logo, select your desired file.

Your logo will be visible on your receipts once printed.

Payment statuses

The table below describes the possible payment statuses and their meanings.

Updates

The table below shows the available methods for receiving payment status updates.

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

Testing

POS transactions are not supported in the TEST environment. All testing must be performed using a LIVE account.

Next step