How do I board ConCardis Merchants via the API?

Your goal is to use the Platform API to create a merchant that can process payments via ConCardis.

This guide shows you how to create a merchant based on the "Merchant Information" that ConCardis has provided to you. It further explains how to assign a reader to the merchant and how to generate a merchant secret key for the 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"
      ],
      "details": {
        "institute": "CONCARDIS",
        "terminalIds": [
          "71E29108", "71E29109"
        ],
        "vuNummers": [
          {
            "schemes": [
              "MASTER"
            ],
            "vuNummer": "153442414"
          },
          {
            "schemes": [
              "MAESTRO"
            ],
            "vuNummer": "353442412"
          },
          {
            "schemes": [
              "VISA","VISAELECTRON"
            ],
            "vuNummer": "143442416"
          }
        ]
      },
      "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" from ConCardis, please provide those parameters:

$.processingPaths.currencies: Provide the Currency
you want to process payments in. Usually its
EUR
.
$.processingPaths.details.terminalIds: Provide all Terminal IDs
that you have received from ConCardis. You can use as many active readers at the same time as you have specified Terminal IDs here, i.e. each active reader needs one Terminal ID.
$.processingPaths.details.vuNummers: Provide the VP Numbers
for all schemes you have received from ConCardis: The number for Visa/Electron/Vpay always starts with 14, the number for MasterCard with 15 and the number for Maestro with 35.
$.processingPaths.name: We recommend to always use "ConCardis" and the currency for this name.
$.name: Make sure to specify a unique name for each merchant that you create on the platform.
$.details: Finally, for the payment receipts, you need to provide some information about the merchant, including Public Name, Address and a Contact Phone Number/Email Address
.

You will receive a

merchantIdentifier

after successfully creating the merchant:

Response


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

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

The platform keeps track of all the readers that you have purchased. In order to assign a reader to the new merchant you have 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:

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 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 in the response:

Response


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