The LCM Merchant Onboarding API is used by Payment Service Providers (PSPs) and Token Requestor Aggregators (TRAs) to enroll merchants for COF status inquiries and Merchant Tokenization services.

After successful onboarding, PSPs and TRAs can:

• Create, read, update, and delete merchant records
• Manage merchant subscriptions for supported services and schemes
• Inquire about card status on behalf of onboarded merchants via AAU batch files
• Request tokenization of cards using tokenization services

Authentication

Before you can use the LCM Merchant Onboarding APIs, your application must complete the on-boarding process.

You will receive two sets of credentials:

• Sandbox credentials (for test transactions)
• Production credentials (for live transactions)

Each set consists of a Client ID and a Client Secret. The Client Secret is confidential and must not be shared.

To invoke this API you must obtain an OAuth 2.0 access token and send it in the HTTP Authorization header as a Bearer token.

Important: The OAuth2 Token/Revoke endpoints are exposed by the Authorization Server (separate host) and are documented here for convenience. They are not part of the Resource Server paths in this OpenAPI document.

OAuth 2.0

OAuth 2.0 is the industry-standard protocol for authorization. See: RFC 6749.

This API supports OAuth 2.0 with the confidential client type. A confidential client can keep its credentials secret when interacting with the Authorization Server.

OAuth 2.0 defines four roles:

1. Resource owner: Entity capable of granting access to a protected resource.
2. Resource server: Server hosting protected resources, accepting requests using access tokens.
3. Client: An application requesting protected resources on behalf of the resource owner.
4. Authorization server: The server issuing access tokens to the client after successful authentication/authorization.

At a high level, the flow is:

1. Get an access token from the Authorization Server.
2. Use the access token to call this API (the Resource Server).

OAuth 2.0 uses an "authorization grant" to represent the authorization used to obtain an access token. This API supports the Client Credentials grant type.

Authorization Server

Token Endpoint

POST /token

With the Client Credentials grant type, the client requests an access token using only its own credentials. The access token returned for this API is of type Bearer.

Clients should request the minimal necessary scope and lifetime. The Authorization Server may issue an access token with fewer rights than requested.

Generate an access token (Client Credentials grant):

1. Obtain a valid client_id and client_secret.
2. Combine them as client_id:client_secret and Base64-encode the result.
3. Call the Token Endpoint. Example:

# NOTE: Only use -k in sandbox/test environments if TLS verification cannot be performed.
curl -k -d "grant_type=client_credentials" \
  -H "Authorization: Basic <Base64 encoded client_id:client_secret>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  https://api-gateway2.nets.eu/token

Example response (access token may be opaque, not necessarily a JWT):

{
  "token_type": "Bearer",
  "expires_in": 2061,
  "access_token": "ca19a540f544777860e44e75f605d927"
}

Note: Per RFC 6749, the Client Credentials grant type does not issue refresh tokens.

Revoke Endpoint

POST /revoke

In case of credential theft or a security incident, revoke an access token using the Revoke Endpoint.

Parameters

• token (required): The token to revoke.
• Basic Authorization header (required): Authorization: Basic <Base64 encoded client_id:client_secret>
• token_type_hint (optional): Use access_token for Client Credentials. If omitted, the server searches multiple token spaces and revocation may take longer.

Example:

curl -X POST \
  https://api-gateway2.nets.eu/revoke \
  -H "Authorization: Basic <Base64 encoded client_id:client_secret>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=<token_to_be_revoked>&token_type_hint=access_token"

Responses

• Valid token - HTTP Status 200 - OK You receive an empty response with the HTTP status as 200. The following HTTP headers are returned:

  Revokedaccesstoken: a0d210c7a3de7d548e03f1986e9a5c39
  Authorizeduser: admin@carbon.super
  Revokedrefreshtoken: 5e87a8235cd4d066e15c4c989f5ecf94
  Content-Type: text/html
  Pragma: no-cache
  Cache-Control: no-store
  Date: Tue, 23 Aug 2018 19:28:52 GMT
  Transfer-Encoding: chunked
  

• Invalid token - HTTP Status 200 - OK You still receive an empty response with the HTTP status as 200 but only the following HTTP headers are returned:

  Content-Type: text/html
  Pragma: no-cache
  Cache-Control: no-store
  Date: Tue, 23 Aug 2018 19:31:45 GMT
  Transfer-Encoding: chunked
  

  Because the authorization server cannot find the token in any key space, you will not see Revokedaccesstoken or Revokedrefreshtoken

API Specification

Content types

Requests must be JSON:

• Content-Type: application/json

Clients SHOULD request JSON responses:

• Accept: application/json

Responses are JSON:

• Content-Type: application/json

Error codes

Error code	Description
AAU-1514	Invalid Request Format
AAU-1516	Invalid Request Data
AAU-1520	Generic exception

Pagination

The GET /merchants endpoint supports two pagination styles:

1. Page-based: query parameters page (1-based index) and size (page size).
2. Keyset (cursor) based: start with a request omitting nextKey; subsequent requests use the nextKey value returned in the previous response for efficient large list traversal.

Request parameters:

• Page-based: page and optional size.
• Keyset-based: optional size and (for continuation only) nextKey.
• Do not send page together with nextKey.

Response fields:

• pageNumber: current page index.
• size: requested page size.
• numberOfElements: elements in current page.
• totalPages: total number of pages (page-based only; may be omitted or zero when using nextKey).
• totalElements: total number of elements (page-based only; may be approximate).
• nextKey: supply this value in the next request to continue.

Usage guidance:

• Use page/size for small result sets or when total counts are needed.
• Use nextKey for large, frequently changing datasets to reduce performance overhead.
• Do not mix nextKey with page; choose one strategy per request.

Examples:

• Page-based initial: GET /merchants?page=1&size=50
• Keyset initial (no cursor yet): GET /merchants?size=50
• Keyset continuation: GET /merchants?nextKey=5130&size=50