> For the complete documentation index, see [llms.txt](https://docs.saferpay.com/home/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.saferpay.com/home/integration-guide/guides-for-solution-developers/customer-onboarding-and-configuration.md).

# Customer onboarding and configuration

When providing a general implementation for a wide selection of merchants, it becomes increasingly important to provide a smooth and easy-to-follow onboarding and configuration experience.

The Management API offers the possibility to automatically configure a Saferpay integration, making the setup faster and more convenient for the merchant. Instead of asking the merchant to manually enter terminal IDs, payment methods and available Saferpay features, the integration can query this information directly, so it may auto-configure itself.

Of course, some basic input from the merchant is required, but keeping it to a controlled minimum reduces the risk of misconfiguration and other mistakes.

This guide will talk you through the best practices and steps needed to achieve this.

## 1 - Data needed from the merchant & environments

The minimum data that is needed from the merchant is the [JSON API User and the API Password](https://docs.saferpay.com/home/master/common-saferpay-terms-glossary.md#api-credentials-api-user-api-password). Everything you need can then be derived from that dataset.

For the live account, these details are not provided by Saferpay for security reasons. Instead, the merchant must create them [inside the Saferpay Backoffice](https://docs.saferpay.com/home/interfaces/backoffice.md). Please refer your customer to the respective place by mentioning this detail and [linking to this chapter in our documentation](https://docs.saferpay.com/home/interfaces/backoffice/settings/json-api-basic-client-certificate-authentication.md).

{% hint style="info" %}
While we do send these details via email for the test environment, the merchant can of course also create new credentials for testing this way.

You can mention this detail and even link directly to the respective logins:

* Test-Environment: <https://test.saferpay.com/bo/login>
* Live-Environment: <https://www.saferpay.com/bo/login>
  {% endhint %}

This way, they are pointed towards the right place and do not have to ask where to get these details.

Furthermore, please note the differences between the Saferpay Live and Test environments. Both environments need a separate configuration on your end, as there is no connection between them, with the merchant having separate test and live accounts respectively.

Besides that, the gateway URL for each environment is also different:

* Test-Environment: **`https://test.saferpay.com/api`**
* Live-Environment: **`https://www.saferpay.com/api`**

It is important to automatically switch between these URLs, based on the currently chosen environment.

Please keep these differences in mind and offer separate configurations and inputs for both environments, at least for User, Password, and the URLs respectively.

The rest of the configuration (available features and payment methods, settings, etc.) may be cached on your end once the auto-onboarding has been executed for the first time for the respective environment, so it can be automatically switched between them.

Alternatively, you can execute the auto-config steps anew each time the environment is changed. However, doing so may require time, as the application needs time to execute and process the requests.

Caching both is certainly preferred performance-wise, though it requires two sets of configurations and a switch mechanism on your end, making the integration more complex.

## 2 - Determine the CustomerId

The [CustomerId](https://docs.saferpay.com/home/master/common-saferpay-terms-glossary.md#customerid) is the main account number of your merchant's account and is needed for basically all requests towards Saferpay, be it this auto-config or actual payments, so we need to determine this value first.

This ID is part of the [API user](https://docs.saferpay.com/home/master/common-saferpay-terms-glossary.md#api-credentials-api-user-api-password) the customer has previously entered into your configuration. It has the following format:

**API\_\<CustomerId>\_\<Suffix>**

So the API User **`API_123456_09876543`** has the CustomerId **`123456`**. Your application needs to extract this ID from the API User, with the underscore (`_`) being the separator for easy splitting.

## **3 - Check the available features and verify the input**

Once the [CustomerId](https://docs.saferpay.com/home/master/common-saferpay-terms-glossary.md#api-credentials-api-user-api-password) has been determined, we can finally execute the first request to auto-configure the integration.

The [Licensing CustomerLicense](https://saferpay.github.io/jsonapi/index.html#rest_customers_customerId_license) request lets you query the account's license configuration, giving you an overview of the available Saferpay features. The integration should use this information to determine which functions and settings are available to the merchant.

For example, the [Saferpay Fields](https://docs.saferpay.com/home/integration-guide/licences-and-interfaces/saferpay-fields.md) should only be selectable if the corresponding feature is included in the account's license. The related settings should otherwise be hidden or disabled.

The same applies to Secure Card Data. Card-on-File settings for Customer Initiated Transactions (CIT) and Merchant Initiated Transactions (MIT) should only be selectable if Secure Card Data is activated on the Saferpay contract. Otherwise, these settings should be disabled, for example by displaying them as greyed-out options.

If a feature is required for the integration to operate, a clear error message should identify the missing feature and advise the merchant to [contact our sales team](https://docs.saferpay.com/home/integration-guide/support.md#worldline-sales-team) or their account manager directly to have it activated.

The merchant can also check the current license and its included features inside the Saferpay Backoffice under [Settings > License overview](https://docs.saferpay.com/home/interfaces/backoffice/settings.md#license-overview).

#### Example

Here is an example of how a response may look:

```json
{
  "Package": {
    "Id": "SAFERPAY_ALL_IN_ONE",
    "DisplayName": "Saferpay all-in-one"
  },
  "Features": [
    {
      "Id": "BATCH_PROCESSING",
      "DisplayName": "Batch Processing"
    },
    {
      "Id": "HOSTED_ENTRY_FORM",
      "DisplayName": "Hosted Entry Form"
    },
    {
      "Id": "HOSTED_REGISTER_FORM",
      "DisplayName": "Hosted Register Form"
    },
    {
      "Id": "OMNICHANNEL",
      "DisplayName": "Omnichannel"
    },
    {
      "Id": "SAFERPAY_FIELDS",
      "DisplayName": "Saferpay Fields"
    },
    {
      "Id": "SECURE_CARD_DATA",
      "DisplayName": "Secure Card Data"
    },
    {
      "Id": "PAYMENT_API",
      "DisplayName": "Payment API"
    },
    {
      "Id": "MANAGEMENT_API",
      "DisplayName": "Management API"
    },
    {
      "Id": "SECURE_PAY_GATE_SINGLE_USE_PAYMENT_LINKS",
      "DisplayName": "Secure PayGate Single-Use Payment Links"
    },
    {
      "Id": "SECURE_PAY_GATE_MULTI_USE_PAYMENT_LINKS",
      "DisplayName": "Secure PayGate Multi-Use Payment Links"
    },
    {
      "Id": "PCI_CARD_NUMBER_UNMASKING",
      "DisplayName": "Card Number Unmasking"
    }
  ]
}
```

Not all of these features are important for your integration, so here is a rundown of the ones that actually matter to you:

<table><thead><tr><th width="385.9375">ID</th><th>Corresponding feature/flow</th></tr></thead><tbody><tr><td><pre><code>PAYMENT_API
</code></pre></td><td>General availability of the Saferpay Payment API. This is probably the most important aspect. Without it, the merchant cannot execute payments via our API in the first place.</td></tr><tr><td><pre><code>HOSTED_ENTRY_FORM
</code></pre></td><td>Availability of the Hosted Card Entry Form and the <a href="https://docs.saferpay.com/home/integration-guide/licences-and-interfaces/transaction-interface.md">Transaction Interface</a>.</td></tr><tr><td><pre><code>SECURE_CARD_DATA
</code></pre></td><td>The availability of <a href="https://docs.saferpay.com/home/integration-guide/licences-and-interfaces/secure-card-data.md">Secure Card Data and Tokenization</a>. Usually used for <a href="https://docs.saferpay.com/home/integration-guide/licences-and-interfaces/transaction-interface/recurring-payments.md">Recurring Payments</a>.</td></tr><tr><td><pre><code>HOSTED_REGISTER_FORM
</code></pre></td><td>The availability of the Hosted Card Registration Form and the <a href="https://docs.saferpay.com/home/integration-guide/licences-and-interfaces/secure-card-data.md#standalone-secure-card-data-registration">Standalone Secure Card Data Registration</a>.</td></tr><tr><td><pre><code>OMNICHANNEL
</code></pre></td><td>The availability of <a href="https://docs.saferpay.com/home/integration-guide/licences-and-interfaces/omni-channel.md">Saferpay Omni-Channel</a>. Enables the transfer of transactions between Saferpay (E-Commerce) and certain Worldline POS solutions.</td></tr><tr><td><pre><code>SAFERPAY_FIELDS
</code></pre></td><td>The availability of the <a href="https://docs.saferpay.com/home/integration-guide/licences-and-interfaces/saferpay-fields.md">Saferpay Fields</a> via the <a href="https://docs.saferpay.com/home/integration-guide/licences-and-interfaces/transaction-interface.md">Transaction Interface</a> and <a href="https://docs.saferpay.com/home/integration-guide/licences-and-interfaces/secure-card-data.md">Secure Card Data</a>.</td></tr><tr><td><pre><code>SECURE_PAY_GATE_SINGLE_USE_PAYMENT_LINKS
</code></pre></td><td>Availability of the <a href="https://docs.saferpay.com/home/interfaces/management-api.md#secure-paygate-links">Secure PayGate payment link creation via Management API</a>.</td></tr></tbody></table>

### Verify the Input

By executing this request successfully, you can also verify the API user, password, and whether the correct environment has been set. Should these be incorrect, Saferpay will respond accordingly:

```json
 {
  "Behavior": "DO_NOT_RETRY",
  "ErrorName": "AUTHENTICATION_FAILED",
  "ErrorMessage": "Invalid credentials"
}
```

Should you get this response, you should tell your customer that either the user or the password is incorrect, or that they have entered them into the wrong environment configuration, as test accounts cannot be used on the live environment and vice versa.

## 4 - Determine the terminal

The terminal is always connected to the CustomerId and can only be used by that account. It contains the information about payment methods, their contracts, available currencies and more.

A merchant may have multiple terminals to cover different use cases. For instance, separate terminals are often used if a merchant is running multiple web shops, franchises, or locations. It may also be interesting for your application to gather information on multiple terminals to offer specific functionality (see the table below).

The Management API is capable of gathering a list of all terminals that are active on this merchant account through the [Terminals GetTerminals request](https://saferpay.github.io/jsonapi/index.html#rest_customers_customerId_terminals). It returns the terminals and their types. You should filter per type if a certain one is needed for your application. The following terminal types may be returned:

<table><thead><tr><th width="141.09765625">Terminal Type</th><th>Usecase</th></tr></thead><tbody><tr><td><strong>ECOM</strong></td><td>This terminal is your normal E Commerce terminal, which should be used for normal web-shop applications and <a href="https://docs.saferpay.com/home/integration-guide/licences-and-interfaces/transaction-interface/recurring-payments.md">recurring payments</a>. So this is used for most of our flows.</td></tr><tr><td><strong>SPG</strong></td><td>This terminal is very similar to the ECOM terminal, but is specifically used for Secure PayGate applications, like the <a href="https://docs.saferpay.com/home/interfaces/management-api.md#secure-paygate-links">creation of payment links through the Management API</a>.</td></tr><tr><td><strong>MPO</strong></td><td>This is a special terminal, that <strong>may only be used for</strong> <a href="https://docs.saferpay.com/home/integration-guide/licences-and-interfaces/mail-phone-order.md"><strong>Mail Phone Order</strong></a> <strong>applications and nothing else</strong>.</td></tr></tbody></table>

If only one terminal of the desired type is returned, your application may display and select it automatically. If there are multiple, please present a selection (through a dropdown or similar).\
If no terminal of the desired type is available, please display a corresponding error message to your customer and point them towards [our sales](https://docs.saferpay.com/home/integration-guide/support.md#worldline-sales-team) or their account manager in sales.

## 5 - Retrieve the terminal configuration

Once the terminal(s) has/have been selected, you can go ahead and gather the configuration of the terminal itself by executing the [Terminal GetTerminal](https://saferpay.github.io/jsonapi/index.html#rest_customers_customerId_terminals_terminalId) (mind the missing "s") request.

The response contains the activated payment methods and the available currencies for each payment method. The module can use this information to configure its payment methods and currencies based on the actual terminal configuration.

It also contains URLs for the currently used payment method logos as .svg files. These can be used for display on your website.

## 6 - Retrieve Payment Page Configuration

The Payment Page configuration is an optional feature that enables the merchant to change certain aspects of the Payment Page, for example a company logo, limited colors and styling, and also the text for the "Buy" button.

By executing the PaymentPageConfig GetConfigurations request, you'll receive a list with all available configurations that you can then submit with the [Payment Page Initialize](https://docs.saferpay.com/home/integration-guide/licences-and-interfaces/payment-page.md#id-1-paymentpage-initialize-request) and also (in limited functionality) for the [Transaction Interface](https://docs.saferpay.com/home/integration-guide/licences-and-interfaces/transaction-interface.md#id-1-transaction-initialize) and [Standalone Secure Card Data](https://docs.saferpay.com/home/integration-guide/licences-and-interfaces/secure-card-data.md#standalone-secure-card-data-registration) registration, in order to control certain aspects of the Hosted Forms.

Similar to the terminal selection, the merchant should be able to (de-)select the configuration. If no configuration is returned, simply display an info message that informs the merchant about it and also that it is an optional feature in general.

## 7 - Set up Saferpay Fields

If the merchant wants to (or has to, depending on your integration) use Saferpay Fields [and the corresponding feature is available](#id-3-check-the-available-features-and-verify-the-input), the [Create Access Token request](https://saferpay.github.io/jsonapi/index.html#rest_customers_customerId_terminals_terminalId_fields-access-tokens) can be used to generate the required access token during setup.

Access tokens that are no longer needed can be removed using [Delete Access Token](https://saferpay.github.io/jsonapi/index.html#rest_customers_customerId_terminals_terminalId_fields-access-tokens_accessToken).

## 8 - Keeping the configuration up to date

The Saferpay account configuration is nothing that is set in stone. It may change, especially when the customer requests new payment methods or features to be activated. Therefore, it may become necessary to execute the above steps again. However, this should be done with restraint.

### What you shouldn't do

You should not execute the auto-config automatically or continue to poll this information, [as polling is prohibited](https://docs.saferpay.com/home/integration-guide/general-information.md#polling). The Management API is intended to be used once for setup and then saved.

Generally speaking, this is not intended to be "overused". Use it if needed and save the information that is returned.

### What you should do

Offer a simple reconfigure button to your merchant, so they may reconfigure the account if the need is really there.

You may also detach certain steps, for instance steps 6 and 7. They are separate from the overall account configuration. You do not need to create a new Fields Access Token only because a new payment method or currency has been enabled. Implementing dedicated buttons for these steps is a good way to keep the amount of requests to a minimum and also enables a merchant to specifically reconfigure a certain detail and not the whole account.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.saferpay.com/home/integration-guide/guides-for-solution-developers/customer-onboarding-and-configuration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
