This set of methods is used to board merchants and its terminals into Fiserv´s backend systems.

Method: POST /api/v1/application

This endpoint is used to create an application, with all needed merchants, eCommerce and terminals data.

The application is the main data structure of the boarding, that will receive an applicationId, to be used as the unique key of the merchant boarding process.

1. Parameters
   a. No parameter needed
2. Payload
   a. Main. Principal Data structure, divided into sections that reflect Omnipay´s data structure. It´s the principal merchant backend repository, and some of the information provided in this section is reused.

Terminal-processing

Optional section, used to provide terminal information, divided into sections that reflect the entitlements, products and / or specific backend data.

This section can be used for all Fiserv´s backend switch and terminal management systems, and users could only provide the respective information.

e-store

Optional section, used to provide eCommerce information, based on the IPG backend needs.

Users can set the eCommerce merchant parameters on IPG, such as limits, hierarchy, check features, terminals, etc.

It also has a section to provide services and features configurations, depending on specific merchant business characteristics.

1. Responses
   a. “200” – OK. Indicates success in the application creation. As explained before, it will not start any backend onboarding, just store all the application data into the systems database. The system will provide the applicationId and applicationStatus will be set to “IN_PROGRESS” that means “the application has an ID generated. Some information is saved, but not been applied yet”.
   The application can be modified if necessary or posted to start the boarding process.
   b. “204” - No register found
   c. “400” - Bad request. Indicates that an error occurred or any invalid data was informed. Doesn´t generate an applicationId nor store data in the internal database. The response provides an explanation message at array “Errors”, that can be used to fix the payload and retry the process.
   d. “401” - Unauthorized request. Indicates an unauthorized access request, user should review the informed token.
   e. “403” - Forbidden request
   f. “500” - Internal Error
   g. “502” - API Error

Method: PUT /api/v1/{Id}

This endpoint is used to change any application data before it is posted to start the onboarding. It will only be accepted if the applicationId exists and the applicationStatus is one of “IN_PROGRESS”, “REJECTED” or “FAIL_PROCESSED”.

1. Parameters
   a. Id – the applicatioId to be changed
2. Payload. All payload fields should be provided, even if it is not to be changed. A recomended strategy is to use a get /api/v1/application method to retrieve all the information stored in the database, and only change the fields necessary.
3. Responses
   a. “200” – OK. Indicates success in the application update into the systems database. The system will keep the same applicationId and applicationStatus.
   b. “204” - No register found
   c. “400” - Bad request. Indicates that an error occurred, or any invalid data was informed. Doesn´t update data in the internal database. The response provides an explanation message at array “Errors”, that can be used to fix the payload and retry the process.
   d. “401” - Unauthorized request
   Indicates an unauthorized access request, user should review the informed token.
   e. “403” - Forbidden request
   f. “500” - Internal Error
   g. “502” - API Error

Method: POST /api/v1/{applicationId}/board

This endpoint is used to start the boarding process for the informed applicationId.

The onboarding process is orchestrated by the system, in an asynchronous process. All the backend system are called according to the information provided and following a pre-defined flow. The system also guarantees the integrity of the boarding in case of any rejection in one of the backend systems involved.

1. Parameters
   a. applicationId – the applicatioId to be changed
2. Payload
   a. No payload needed
3. Responses
   a. “200” – OK. Indicates success in the application post.

🚧

Attention: as explained the boarding process is asynchronous, and the 200 response for the this method only indicates that the post command was accepted with success, and the application is being managed by the system.

The system will keep the same applicationId and applicationStatus, will vary according to the advance of the boarding flow:

• QUEUED - The application has been successfully queued for processing. Please wait for further updates on the application status.
• BOARDING_PROCESS - Started boarding Process.
• FAIL_PROCESSED - Has been processed, but has failed.
• SUCCESSFUL_PROCESSED - Has been successfully processed.
  b. “204” - No register found
  c. “400” - Bad request. Indicates that an error occurred, and the application was not posted. The response provides an explanation message at array “Errors”, that can be used to fix the payload and retry the process.
  d. “401” - Unauthorized request. Indicates an unauthorized access request, user should review the informed token.
  e. “403” - Forbidden request
  f. “500” - Internal Error
  g. “502” - API Error

OpenFx

This set of methods is used to provide Dynamic Currency Conversion (DCC) margins, into Fiserv´s backend system named OpenFx.

Method: POST /api/v1/openfx-margins

This endpoint is used to create or update the margins for a merchant.

It should be used linked to an application previously created and not boarded yet. When this application is posted to start the boarding process, the flow will include the Openfx steps in the system´s orchestration.

1. Parameters
   a. No parameter needed
2. Payload
   a. ApplicationId. The applicationId, link to the application stored into system´s database, that is creating the merchant boarding data.
3. Margins. Parameters of DCC margins to be set to the merchant, defining values and services.
4. Responses
   a. “200” – OK. Indicates success in the margins´ post.

🚧

Attention: as explained the backend system will be updated only when the boarding process is completed.

b. “204” - No register found
c. “400” - Bad request. Indicates that an error occurred, and the application was not posted. The response provides an explanation message at array “Errors”, that can be used to fix the payload and retry the process.
d. “401” - Unauthorized request. Indicates an unauthorized access request, user should review the informed token.
e. “403” - Forbidden request
f. “500” - Internal Error
g. “502” - API Error

Method: GET /api/v1/openfx-margins/application/{applicationId}

This endpoint is used to retrieve the margins linked to an application.

1. Parameters
   a. applicationId – the applicatioId to retrieve the stored margins
2. Payload
   a. Not used
3. Responses
   a. “200” – OK. Indicates success in the application´s margins retrieval. The response will provide all margins values and services stored in systems database.
   b. “204” - No register found
   c. “400” - Bad request
   d. “401” - Unauthorized request. Indicates an unauthorized access request, user should review the informed token.
   e. “403” - Forbidden request
   f. “500” - Internal Error
   g. “502” - API Error

Method: DELETE /api/v1/openfx-margins/application/{applicationId}

This endpoint is used to delete the margins linked to an application.

1. Parameters
   a. applicationId – the applicationId to delete the stored margins
2. Payload
   a. Not used
3. Responses
   a. “200” – OK. Indicates success in the application´s margins deletion. When the referenced application boarding started, the Openfx will not be part of the flow, and margins will not be set to the respective merchant. The response will provide all margins values and services delete from systems database.
   b. “204” - No register found
   c. “400” - Bad request
   d. “401” - Unauthorized request. Indicates an unauthorized access request, user should review the informed token.
   e. “403” - Forbidden request
   f. “500” - Internal Error
   g. “502” - API Error

Terminal

This set of methods is another way, used to provide terminal information, divided into sections that reflect the entitlements, products and / or specific backend data.

The function is the same as described in section 3.a.2.b of this document. The only difference is that this option can be used after the application was created.

Method: POST /api/v1/terminal/save-all

This endpoint is used to create or update the terminals under an application to be boarded.
It should be used linked to an application previously created and not boarded yet. When this application is posted to start the boarding process, the flow will include the terminal steps in the system´s orchestration.

1. Parameters
   a. No parameter needed
2. Payload
   a. ApplicationId. The applicationId, link to the application stored into system´s database, that is creating the merchant boarding data.
3. Terminals. Used to provide terminal information, divided into sections that reflect the entitlements, products and / or specific backend data.
   This section can be used for all Fiserv´s backend switch and terminal management systems, and users could only provide the respective information.

4. 🚧

   Responses

   a. “200” – OK. Indicates success in the terminals´ post.
   Attention: as explained the backend systems will be updated only when the boarding process is completed.

b. “204” - No register found
c. “400” - Bad request. Indicates that an error occurred, and the application was not posted. The response provides an explanation message at array “Errors”, that can be used to fix the payload and retry the process.
d. “401” - Unauthorized request. Indicates an unauthorized access request, user should review the informed token.
e. “403” - Forbidden request
f. “500” - Internal Error
g. “502” - API Error