API for Individual Online Orders

This course describes REST API for the Online Ordering module which is part of the ALIVE Platform information system. Online Ordering module is intended for individual online card orders which are usually paid directly by applicants. GUI administration side of the module is accessible for ISIC staff to process the orders while automated emails are triggered and sent to applicants to inform them about the processing status of their orders.

Main purpose of this API is the possibility to integrate it into third party solutions, websites, mobile apps etc., so the customers can place card orders without actually touching the Online Ordering form. Through the API, only one card order per request can be created.

Before you start using the API, you have to make an authentization through an existing user account. Basically, you can authenticate through following types of accounts:

User of Card Issuer „Online Ordering“

User of Online Ordering Affiliate Partner

User of Card Issuer Integrated with Online Ordering

All these accounts should be set up in NCDB. For our use case (see next lessons), we’re going to place orders through an account of Online Ordering Affiliate partner.

In this section, we are going to have a look at a typical use case. Please, imagine the following situation:

You have an Online Ordering Affiliate Partner called „TestPartner“. This partner of yours wants to implement the API, so it would be possible to place card orders through its mobile application. TestPartner takes care of all payments for online orders on its side and only reports back to the ALIVE Platform that the orders have been paid.

TestPartner issues virtual cards and also possiblity to order virtual + plastic card should be allowed.

TestPartner requires photo, as well as identity document and confirmation of study/teaching to be uploaded.

Customers can choose that they will pick up their card personally or the card will be delivered to them by post registered letter. For virtual only cards, delivery method will be of course “email”.

In this course, we will deal mostly with this use case. Other use cases can be found in full documentation to this API .

Introduction When talking about APIs, terms „request“ and „response“ will be frequently used. A request is usually triggered through a customer’s action. The „response“ is the answer from the server. In our example, in the mobile app created by TestPartner, when a customer fills in all his personal data into a form and confirms the form, the request POST /cardOrders is triggered. If everyting in OK, the response confirming that the card order was created will be sent back to the app. Following examples will be shown in software Insomnia for API’s testing. Within this software, you can simulate the requests and responses. For test purpose, any other REST client can be used. In all cases, we are going to test the API against test environment of the ALIVE Platform (with URL https://cz-online.test.aliveplatform.com/api/1.0). Note: To find out all possible values for API variables, feel free to use Swagger documentation, which can be found at https://cz-online.test.aliveplatform.com/api/1.0/doc. Within Swagger, you can also play around in an integrated sandbox to test the requests with different variables. Into Swagger, you can log in using your credentials for test environment of the ALIVE Platform. Settings for Online Ordering Affiliate Partner and its User in NCDB As a first step, Online Ordering Affiliate Partner TestPartner from our usecase has to be set up in NCDB.

Open

Next, let’s set up a new user for TestPartner.

Open

Now, everything in NCDB is well set up and we can move on. GET API /settings Using GET /settings endpoint, you can have a look at how the TestPartner is set up, which values are possible for variables etc. This can be very useful when formulating next requests.

Whole request for test environment for our TestPartner looks like:

POST /cardOrders At the moment your customer fills in the form in third party application and confirms inserted data, the app sends the POST /cardOrders request. Within this request, you define all things that the customer normally inserts into Online Ordering form, when ordering through standard GUI. Let’s take a look how this request looks in our test software.

PUT /documents As a next step, the customer needs to upload all mandatory documents. In our example, documents photo, identity document and confirmation of study/teaching are required. Through the API, the documents have to be sent as image/jpeg Content-Type. The requests for different documents are as follows:

As {orderId}, the ID which we got in response to POST /cardOrders should be added. Through the API, you can of course check whether the photo or any other document has been successfully uploaded using quite similar GET request:

Whole request for getting the photo looks like:

PUT /status Untill this moment, the cardOrder has been stored, but not displayed within Online Ordering administration. To make it visible, let’s change the state of this card order using PUT /status request.

The states to which we can push this order (in our particular example) are „ORDERED“ and „PAID“.

Now, our card order is displayed within Online Ordering application and can be further processed, exported into NCDB etc. From this point, the process is exactly the same as for card orders placed through Online Ordering form.

Schema of API requests Now, you are probably a little confused about the described process. Let’s have a look at the following schema, which hopefully shows the workflow in more understandable way.

In our example from previous section, we have just pushed the card order into „PAID“ status, so it was displayed in Online Ordering application as „Paid“. This is possible only for the case in our example, which means „the Partner takes care of all payments of online orders on its side and only reports that the orders have been paid.„, as was defined for our use case. That’s why we used „EXTERNAL_PAYMENT“ as payment method in POST /cardOrders request and why we allowed „Allow External Payments (via API)“ in the profile of our TestPartner. In case the Online Ordering Affiliate Partner doesn’t take care of payments on its side, in PUT /cardOrders request, another payment method should be specified (such as PAYPAL, COMGATE, etc. – see the documentation or Swagger). In such a case, the customer should pay for the card using the link for payment, which can be integrated into automated „Order created“ email template in Online Ordering administration.

As you know, during the process of placing and processing card orders through the Online Ordering, automated emails are sent to customers. These automated emails work exactly the same in case Online Ordering API is used. Which means:

When card order is placed through the API and it is put into „ORDERED“ status, your defined email „Order created“ (possibly with URL link for payment gate) is sent.

After the customer pays for the card, email „Order paid“ is sent.

Also email „Unpaid order reminder“ is sent repeatedly in case the payment for the order hasn’t been done.