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.

⚠️
Note:
Using an incorrect API key can cause subsequent API calls associated with that order to fail.

How to cancel an order

You can cancel an order:

How to process a refund

You can process refunds:

Receipts

You can retrieve receipt details:

Device management

You can manage your devices:

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:

Sign in to your MultiSafepay dashboard.
Go to Devices > Terminals.
Click Manage groups.
Click + Add new group.
Insert a name for your group, and optionally, a logo to enable branding, and a Webhook URL to receive updates for your payments.
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:

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

How to edit a group

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.

Click Save 💾.

💡
Tip! You can view your API key via Manage groups > API key.

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.

Go to your MultiSafepay dashboard .
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.

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

Once your logo has been uploaded:

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

Your logo will be visible on your receipts once printed.

⚠️
Note:
Logos are displayed in the MultiSafepay payment app only when using the Cloud POS payment flow. For all other payment flows, custom logos are visible only in your MultiSafepay dashboard.

Payment statuses

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

Description	Payment status
The card scheme is processing your payment request.	Initialized
The payment has been cancelled on the device or via API, or has expired after 60 seconds of inactivity. For more information - see Cancellation. Note: You can now initiate another cloud POS payment.	Cancelled
The customer has completed the payment. Note: You can now initiate another cloud POS payment.	Completed
The card scheme has declined the payment. The customer will be redirected to the payment screen to retry the payment. In certain cases, a payment may be soft declined, meaning the customer must authenticate to proceed with the transaction. For more information, see Soft declines - SmartPOS solutions.	Declined

Updates

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

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.

⚠️
Note:
Finalized POS transactions will always have a status of completed or cancelled. A declined status might indicate a soft decline, which is not a final state. For more information, see Soft declines.

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

Example response

  {
  "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 are not supported in the TEST environment. All testing must be performed using a LIVE account.

Operations guide

Authentication

Note:

How to cancel an order

How to process a refund

Receipts

Device management

Terminal groups

How to create a terminal group

How to edit a group

How to set up your logo for Cloud mode

Note:

Payment statuses

Updates

Note:

Testing

Next step