How do I board a Nexi Merchant via the API?

Boarding a Merchant via an API

Follow these steps to use the

Platform

API to create a merchant and board that can process payments using Nexi. These steps also provide instructions about how to assign a card reader to the merchant and how to generate a merchant secret key for the new merchant. You will use the merchant information that Nexi provides to you to create a new merchant.

1. Create a merchant with

CONCARDIS

as the processing path.

post

/v2/merchants/

Try it out!

Request

{
  "processingPaths": [
    {
      "currencies": [
        "EUR"
      ],
      "schemes": [
        "VISA",
        "MASTER",
        "MAESTRO",
        "VISAELECTRON",
                "UNION_PAY",
                "JCB",
                "DINERS",
                "DISCOVER"
      ],
      "details": {
        "institute": "CONCARDIS",
        "terminalIds": [
          "71E29108", "71E29109"
        ],
        "vuNummers": [
           {
            "schemes": [
              "MASTER"
            ],
            "vuNummer": "153442414"
          },
          {
            "schemes": [
              "MAESTRO"
            ],
            "vuNummer": "353442412"
          },
          {
            "schemes": [
              "VISA","VISAELECTRON"
            ],
            "vuNummer": "143442416"
          },
          {
                        "schemes": [
              "DINERS","DISCOVER"
            ],
            "vuNummer": "577777776"
          },
          {
                  "schemes": [
              "UNION_PAY"
            ],
            "vuNummer": "487777776"
          },
          {
                  "schemes": [
              "JCB"
            ],
            "vuNummer": "537777776"
          }
        ]
      },
      "name": "ConCardis EUR"
    }
  ],
  "readers": [],
  "name": "Test Merchant #42",
  "details":{  
      "publicName":"Public Merchant Name",
      "address":"42 Merchant Street",
      "zip":"123456",
      "city":"Merchant City",
      "country":"DE",
      "contact":"+49 (170) 1234567"
   }
}

Based on the merchant information provided to you by Nexi, enter those parameters:

$.processingPaths.currencies: Provide the Currency
for which you want to process payments. The value is typically
EUR
.
$.processingPaths.details.terminalIds: Provide all Terminal IDs
that you received from Nexi. You can use as many active readers at the same time as you have specified Terminal IDs here. Each active reader must have have one Terminal ID.
$.processingPaths.details.vuNummers: Provide the VP Numbers for all schemes you received from Nexi. The VP Number for Visa/Electron/Vpay always starts with
14
, the VP number for MasterCard starts with
15
and the VP number for Maestro starts with
35
.
$.processingPaths.name: We recommend always using Concardis
and the currency for this name.
$.name: Specify a unique name for each merchant that you create on the platform.
$.details: For the payment receipts, you must provide this information about the merchant:
Public name
Address
Contact phone number/email address

After successfully creating the merchant, you will receive a

merchantIdentifier

in the response message:

Response

{
    "status": "ok",
    "data": {
        /*...*/
        "identifier": "74b47dcd-45b0-4c65-a4d1-afd4aae32708",
        "name": "Test Merchant #42"
                /*...*/
    }
}

2. Find the card reader that you want to assign to the merchant.

The platform tracks all of the card readers that you purchased. In order to assign a reader to the new merchant you created in step 1, you must know its

readerIdentifier

. Use this API to find the

readerIdentifier

of a reader based on its serial number (e.g., 999-100001):

get

/v2/readers/?search=999100001

Try it out!

Request

You will receive the

readerIdentifier

in the response message:

Response

{
    "status": "ok",
    "data": [{
        /*...*/
        "identifier": "0665ede3-3990-4c9b-beac-77abfeda5858",
        "model": "MIURA_SHUTTLE",
        "details": {
            "serialNo": "999100001"
            /*...*/
        }
    }]
}

3. Assign the reader to new merchant.

Based on the

merchantIdentifier

from step 1 and the

readerIdentifier

from step 2, you can now assign the card reader to the merchant:

put

/v2/merchants/{merchantIdentifier}/readers/{readerIdentifier}

Try it out!

Request

4. Generate the merchant secret key

You can also generate a merchant secret key for the Merchant via the API:

post

/v2/merchants/{merchantIdentifier}/secretKey

Try it out!

Request

{
        "permissions": ["READER_MANAGEMENT","TRANSACTIONS"]
}

You will receive the merchant secret key (

key

) in the response:

Response

{
    "status": "ok",
    "data": {
        "status": "ACTIVE",
        "key": "9pCcTI2mzUbLKoCdezVBowhv0b6gGwoo"
    }
}