🏁How to start?

This page includes how to get started with AAZZUR APIs and some guidelines that are going to make your life easier when you are working with the APIs.

First Login and Signup Flow

First-time users at AAZZUR APIs, welcome. Read through the following topics to know how you can get started with the APIs from how to create your new account.

Most of the APIs work with oauth-based authentication, so when making a request you will have to pass the oauth token as well. But the question is how do you even get this token or create a customer account?

Steps to create your first customer account

As I have said before you will be required to put the oauth token with the request but when creating the account you do not really need it because you do not even have the credentials to have the oauth token. So, you have to create a customer with customer information and then you can use that information to get the oauth token.

Before creating a new customer, make sure to read the privacy policy of the platform. To get the privacy policy along with some other default configuration make a GET request to the below API.

getFeatures

GET//appsettings:8080/v1/configuration

Response

200401403404

OK

Body

application/json

configurationKeystring

configurationValueobject

Request

JavaScriptCurl

const response = await fetch('//appsettings:8080/v1/configuration', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

[
  {
    "configurationKey": "text"
  }
]

A sample response to the request is given below:

[
    {
        "configurationKey": "SHARE_ACCOUNT",
        "configurationValue": "ENABLED"
    },
    {
        "configurationKey": "NEW_ACCOUNT",
        "configurationValue": "ENABLED"
    },
    {
        "configurationKey": "SLIPS",
        "configurationValue": "ENABLED"
    },
    {
        "configurationKey": "ADD_CARD_VIRTUAL_CARD_LIMIT",
        "configurationValue": "3"
    },
    {
        "configurationKey": "ADD_CARD_CARD_LIMIT",
        "configurationValue": "3"
    },
    {
        "configurationKey": "EXTERNAL_ACCOUNTS",
        "configurationValue": "OFF"
    },
    {
        "configurationKey": "CURRENCY_EUR",
        "configurationValue": "ENABLED"
    },
    {
        "configurationKey": "TRAVEL_PACK",
        "configurationValue": "OFF"
    },
    {
        "configurationKey": "AAZZUR_WEBSITE",
        "configurationValue": "https://www.aazzur.com/"
    },
    {
        "configurationKey": "AAZZUR_CONTACT",
        "configurationValue": "[phone]"
    },
    {
        "configurationKey": "SPLIT_BILL",
        "configurationValue": "ENABLED"
    },
    {
        "configurationKey": "SIGNUP",
        "configurationValue": "ENABLED"
    },
    {
        "configurationKey": "ADD_CARD_PHYSICAL_CARD_LIMIT",
        "configurationValue": "3"
    },
    {
        "configurationKey": "CARDS_TNC",
        "configurationValue": "https://www.aazzur.com/consumer-cardholder-terms/"
    },
    {
        "configurationKey": "AAZZUR_HELP_CENTER",
        "configurationValue": "https://www.aazzur.com/aazzur-faq/"
    },
    {
        "configurationKey": "ADD_CARD",
        "configurationValue": "ENABLED"
    },
    {
        "configurationKey": "CURRENCY_GBP",
        "configurationValue": "OFF"
    },
    {
        "configurationKey": "SEPA_ADDRESS",
        "configurationValue": "OFF"
    },
    {
        "configurationKey": "AAZZUR_TNC",
        "configurationValue": "https://www.aazzur.com/terms-and-conditions/"
    },
    {
        "configurationKey": "AAZZUR_PRIVACY_POLICY",
        "configurationValue": "https://www.aazzur.com/aazzur-privacy-policy/"
    },
    {
        "configurationKey": "NEW_ACCOUNT_ACCOUNT_LIMIT",
        "configurationValue": "5"
    }
]

You can extract the links from the response.

Creating the customer account

After you are done with the terms and conditions now it's time for you to make the customer profile with your email, password and other details.

To create a user with the v1/customers/me endpoint by providing customer information such as email, password, identity like first name, last name, etc. The createCustomer endpoint is given below:

createCustomer

POST//customers:8080/v1/customers

Header parameters

Body

application/json

body

email*string

passportInfoPassportInfo

password*string

consentsarray of Consent

languagestring

Response

201202401403404

Created

Request

JavaScriptCurl

const response = await fetch('//customers:8080/v1/customers', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "email": "text",
      "password": "text"
    }),
});
const data = await response.json();

A sample JSON request body is given below as well. Have a look at the consent object, there are terms and conditions that you will have to show to the users that they have read it and there can be a checkbox or a button to take their consent that they have agreed to all the terms and conditions.

{
  "email": "[e-mail]",
  "password": "1234",
  "language": "en-US",
  "consents": [
    {
      "accepted": true,
      "type": "CARD_TERMS_AND_CONDITIONS"
    },
    {
      "accepted": true,
      "type": "PRIVACY_POLICY"
    },
    {
      "accepted": true,
      "type": "TERMS_AND_CONDITIONS"
    },
    {
      "accepted": true,
      "type": "PRODUCT_UPDATES"
    },
    {
      "accepted": true,
      "type": "NEWSLETTER"
    }
   ],
  "passportInfo":{
    "firstName": "John",
    "lastName": "Doe",
    "title": "Mr"
  }
}

The response is going to send an id that is referencing your account.

Getting the token with the created customer

As you have already made a customer with the above request, now you can get a token with the email and password that you provided on the last request. To get the oauth you will have to use the below API along with the email and password.

curl localhost:8080/sessions/oauth/token -u [e-mail]:pass -d grant_type=password -d username=[e-mail] -d password=1234

The response would look something like this:

{
    "access_token": "SAMPLE ACCESS TOKEN",
    "token_type": "bearer",
    "expires_in": 1799,
    "scope": "signup",
    "clientId": "app",
    "anyDeviceUser": false,
    "customerId": "SAMPLE CUSTOMER ID",
    "userType": "CUSTOMER",
    "userId": "SAMPLE USER ID",
    "programme": "AAZZUR",
    "username": "[e-mail]",
    "jti": "*********"
}

You can extract the access token from the response and use it on your future request.

The access token will be valid for 30 minutes. It is not possible to extend its duration, after it is expired user should be asked to enter his credentials to obtain the token again.

Checking the sign-up status

After creating the customer account, you will have to add additional information to use the other APIs for example document verification, PIN, address verification, etc.

To get the status of the sign-up process, you will have to use the /v1/customers/me API. The response is going to have the topics that need to be verified.

You will have to use the oauth token from the previous request and use as the bearer token on this request.

getCurrentCustomer

Required scopes - signup

GET//customers:8080/v1/customers/me

Response

200401403404

OK

Body

application/json

addressAddress

applicationStateenum

INITIATEDPENDINGACCEPTEDREJECTED

bundlesarray of string

consentsConsents

customerStateenum

INITIATEDENROLLMENT_STARTEDENROLLEDREJECTEDPENDING

dateOfBirthstring (date)

emailstring

firstNamestring

genderenum

MALEFEMALEOTHER

idstring

languagestring

lastNamestring

nationalitystring

numberOfTokensinteger (int64)

phoneNumberstring

programmestring

shippingAddressAddress

titlestring

unsatisfiedRequirementsarray of enum

Request

JavaScriptCurl

const response = await fetch('//customers:8080/v1/customers/me', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "address": {
    "details": {
      "city": "text",
      "country": "text",
      "firstLine": "text",
      "postCode": "text",
      "state": "text"
    }
  },
  "applicationState": "INITIATED",
  "bundles": [
    "text"
  ],
  "consents": {
    "cardTermsAndConditions": false,
    "newsletter": false,
    "privacyPolicy": false,
    "productUpdates": false,
    "termsAndConditions": false
  },
  "customerState": "INITIATED",
  "dateOfBirth": "2024-05-06",
  "email": "text",
  "firstName": "text",
  "gender": "MALE",
  "id": "text",
  "language": "text",
  "lastName": "text",
  "nationality": "text",
  "phoneNumber": "text",
  "programme": "text",
  "shippingAddress": {
    "details": {
      "city": "text",
      "country": "text",
      "firstLine": "text",
      "postCode": "text",
      "state": "text"
    }
  },
  "title": "text",
  "unsatisfiedRequirements": [
    "PERSONAL_INFO"
  ]
}

A sample sample is given below:

{
    "id": "123123123123",
    "email": "[e-mail]",
    "firstName": "John",
    "lastName": "Doe",
    "language": "en-US",
    "numberOfTokens": 500,
    "unsatisfiedRequirements": [
        "EMAIL_VERIFICATION",
        "PIN",
        "DOCUMENT_VERIFICATION",
        "ADDRESS",
        "PHONE_VERIFICATION"
    ],
    "title": "Mr",
    "consents": {
        "privacyPolicy": true,
        "termsAndConditions": true,
        "newsletter": true,
        "productUpdates": true,
        "cardTermsAndConditions": true
    },
    "programme": "AAZZUR",
    "bundles": [
        "123123123"
    ]
}

As you can see from the above sample response, there is a property unsatisfiedRequirements that has a list of strings. For this customer, the below things are yet to be verified:

• Email Verification

• PIN Setup

• Document (Passport Number/KYC/Other) Verification

• Address Verification

• Phone Number Verification

Providing User Feedback

Providing user feedback is the most important part of the process and it can be quite complicated when you are just starting out. For example, when starting out you will have to make sure that the customer understands why there is a long list of things they have to do before using the services.

There can be a checklist on the UI so that the users of the app can understand what is still needed to be completed. You can make multiple requests to the /v1/customers/me API to see if there is any update on the items.

Document Verification

For verifying the document, it has to be made from the backoffice where you can access the customer information. You can also set the document verification status over there as well. After setting the verified status on the document from the backoffice, the document verification is going to be removed from the unsatisfiedRequirements list.

Customer Login

After you are done with fulfilling the unsatisfiedRequirements list, when you make the request again, it will have an empty list. That indicates that the sign-up flow is completed and you can finally login to the application to do the other work such as ordering a card, make transactions, etc.