Authentication

Our authentication is based on the JWT token. In order to proceed with other REST API calls or JS SDK usage in your web application, you need to request an access token.

Token holds authentication information along with all the parameters required for specific user to communicate with Checkout API including environment that the user is associated with. This allows to connect to test environment without code changes, by just using test user credentials for authentication. All information about the environment will be included inside the token.

Important

For every customer session a new token should be generated and shared with web or mobile application.

Checkout API authentication should be done on the Merchant's backend with same basic authentication credentials, that used for AltaPay Gateway authentication:

AUTH=$(echo -ne "$USERNAME:$PASSWORD" | base64)

curl \
  --header "Authorization: Basic $AUTH" \
  --request POST \
  https://{checkout-api-url}.altapaysecure.com/checkout/v1/api/authenticate

Response will be a JSON with token field, that contains JSON Web Token.

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJBbHRhUGF5IElzc3VlciIsInVwbiI6ImNoZWNrb3V0X2FwaSIsImdyb3VwcyI6WyJTZXNzaW9uVXBkYXRlIiwiRXhlY3V0ZVBheW1lbnQiLCJMaXN0UGF5bWVudE1ldGhvZHMiXSwiYXV0aElkIjoiZjE5YjkxZDctZDVmZS00NzFlLTkwM2EtM2JiYTk0Y2FhYzQ4IiwiaWF0IjoxNjcwOTQyMzk5LCJleHAiOjE2NzA5NDQxOTksImp0aSI6IjVhY2ZjNTgwLWQ2NjAtNDFmMS05NTJmLTBkY2ZjODRiZWM5OCJ9.XUq8AvEEEeURB-tUF2sIzUj7RdirjWJWC1NvGJsyucI0AteOxyWqnJ4zJzTe0BM61vm9Fuu6czsPhh2OqhMdolYmnDsMBDQgoIDhasr5-TukKkIWUJWIfZXsbjJHd8o8-cT70lciDO4pZhp3a16kG-mn6gtY_ezLkcbOtlExv7R0XiLy4qV5vZt1Q6mBPeyy0nEeMhjsud5ZkKMWjqLAh3LqQP2V5_W5UiGo1EPE9P-qNTDUpQolREyWaNbhQwPoverjaGq-xxTNikpJLPAwux4ytmDhAnyt_L7QlAmltRyKegIQIyKpKCKs62cOz7yj7sad_aROefH2jFgEDf6Eqg"
}

Important

For security reasons token expires every 1 hour.

This token will be used to initialize Checkout API session for customer. You can either create the session on the backend side or delegate everything to our JS SDK. This way you can complete your customer's payment securely and your backend services will be called with notifications (and callbacks if configured).

If you are interested in more complex scenarios, please follow the sections below to learn more about different access levels.

Access levels

In order to provide adequate levels of security, we are supporting 2 levels of access:

1. CUSTOMER - this is a default access level, giving the write and read access only to the session created using given access token. It is meant to for customer (frontend application) use.
2. MERCHANT - this is giving you access to all the data associated with given API user. It is meant for background processes and server side processing

In order to specify details about the token you're issuing you need to provide following parameters inside application/json body:

Parameter	Type	Description	Optional
role	enum	Defines the request role for the access token. Allowed values: CUSTOMER, MERCHANT	yes
sessionId	UUID	ID of the checkout session that access should be granted to requested token. Applicable only for CUSTOMER role, when you want to grant it the access to already created session.	yes

The most basic authentication request:

AUTH=$(echo -ne "$USERNAME:$PASSWORD" | base64)

curl \
  --header "Authorization: Basic $AUTH" \
  --request POST \
  https://{checkout-api-url}.altapaysecure.com/checkout/v1/api/authenticate

will create a CUSTOMER token, that will allow you to create a session and finalise the payment process.

If you want to issue CUSTOMER token explicitly specifying role, please see example below - results will be the same.

AUTH=$(echo -ne "$USERNAME:$PASSWORD" | base64)

curl --request POST https://{checkout-api-url}.altapaysecure.com/checkout/v1/api/authenticate \
  --header "Content-Type: application/json" \
  --header "Authorization: Basic $AUTH" \
  --data '{
            "role": "CUSTOMER"
          }'

If you want to issue CUSTOMER token for already created session, you need to specify sessionId field:

AUTH=$(echo -ne "$USERNAME:$PASSWORD" | base64)

curl --request POST https://{checkout-api-url}.altapaysecure.com/checkout/v1/api/authenticate \
  --header "Content-Type: application/json" \
  --header "Authorization: Basic $AUTH" \
  --data '{
            "role": "CUSTOMER",
            "sessionId": "$SESSION_ID"
          }'

In order to get MERCHANT token to do background processing or fetch some historical data, you need to specify role:

AUTH=$(echo -ne "$USERNAME:$PASSWORD" | base64)

curl --request POST https://{checkout-api-url}.altapaysecure.com/checkout/v1/api/authenticate \
  --header "Content-Type: application/json" \
  --header "Authorization: Basic $AUTH" \
  --data '{
            "role": "MERCHANT"
          }'

Advanced examples

Server to server usage

sequenceDiagram
  participant Merchant Service
  participant Checkout API

   activate Merchant Service
   Note left of Merchant Service: Create MERCHANT token
   Merchant Service->>Checkout API: POST /v1/api/authenticate
   Checkout API-->>Merchant Service: MERCHANT JWT token

   Note over Merchant Service,Checkout API: Perform any backend operation like:

   Note left of Merchant Service: Create a session
   Merchant Service->>Checkout API: POST /v1/api/session with MERCHANT JWT token
   Checkout API-->>Merchant Service: session data

   Note left of Merchant Service: Fetch status of a payment
   Merchant Service->>Checkout API: GET /v1/api/payment/{paymentId} with MERCHANT JWT token
   Checkout API-->>Merchant Service: payment info

   Note left of Merchant Service: Generate payment link
   Merchant Service->>Checkout API: POST /v1/api/session/{sessionId}/link with MERCHANT JWT token
   Checkout API-->>Merchant Service: payment link data

   deactivate Merchant Service

If you want to interact with multiple checkout sessions on you backend service (for example to retrieve some extra data) you should use MERCHANT access token that will permit you to access data of all sessions created for this API user credentials.

In order to obtain such token you need to authenticate using role = MERCHANT:

AUTH=$(echo -ne "$USERNAME:$PASSWORD" | base64)

curl --request POST https://{checkout-api-url}.altapaysecure.com/checkout/v1/api/authenticate \
  --header "Content-Type: application/json" \
  --header "Authorization: Basic $AUTH" \
  --data '{
            "role": "MERCHANT"
          }'

Frontend only customer usage

sequenceDiagram
   participant Merchant Service
   participant Merchant Website
   participant Checkout API

   activate Merchant Service
   Note left of Merchant Service: Create CUSTOMER token
   Merchant Service->>Checkout API: POST /v1/api/authenticate
   Checkout API-->>Merchant Service: CUSTOMER JWT token
   deactivate Merchant Service

   Note over Merchant Service,Merchant Website: Pass JWT token to the Web App

   activate Merchant Website
   Note left of Merchant Website: Create a session
   Merchant Website->>Checkout API: POST /v1/api/session with CUSTOMER JWT token
   Checkout API-->>Merchant Website: session data

   Note left of Merchant Website: Create new payment
   Merchant Website->>Checkout API: POST /v1/api/payment with CUSTOMER JWT token
   Checkout API-->>Merchant Website: new payment instructions 

   Note left of Merchant Website: Fetch status of a payment
   Merchant Website->>Checkout API: GET /v1/api/payment/{paymentId} with CUSTOMER JWT token
   Checkout API-->>Merchant Website: payment info

   deactivate Merchant Website

If you want to use the token purely on the frontend application you should use CUSTOMER token, by either requesting it explicitly:

AUTH=$(echo -ne "$USERNAME:$PASSWORD" | base64)

curl --request POST https://{checkout-api-url}.altapaysecure.com/checkout/v1/api/authenticate \
  --header "Content-Type: application/json" \
  --header "Authorization: Basic $AUTH" \
  --data '{
            "role": "CUSTOMER"
          }'

or using a short-cut default:

AUTH=$(echo -ne "$USERNAME:$PASSWORD" | base64)

curl --request POST https://{checkout-api-url}.altapaysecure.com/checkout/v1/api/authenticate \
  --header "Authorization: Basic $AUTH"

Both ways will return CUSTOMER token, that will allow to access only the session created using this token. This is security restriction to prevent customers from seeing each others data.

One backend side token + customers' frontend tokens

sequenceDiagram
   participant Merchant Service
   participant Merchant Website
   participant Checkout API

   activate Merchant Service
   Note left of Merchant Service: Create MERCHANT token
   Merchant Service->>Checkout API: POST /v1/api/authenticate
   Checkout API-->>Merchant Service: MERCHANT JWT token

   loop For every customer session
      Note left of Merchant Service: Create a session
      Merchant Service->>Checkout API: POST /v1/api/session with MERCHANT JWT token
      Checkout API-->>Merchant Service: session data

      Note left of Merchant Service: Create CUSTOMER token
      Merchant Service->>Checkout API: POST /v1/api/authenticate with sessionId specified
      Checkout API-->>Merchant Service: CUSTOMER JWT token

      Note over Merchant Service,Merchant Website: Pass JWT token to the Web App

      activate Merchant Website
      Note left of Merchant Website: Load a checkout session
      Merchant Website->>Checkout API: GET /v1/api/session/{sessionId} with CUSTOMER JWT token
      Checkout API-->>Merchant Website: session data

      Note left of Merchant Website: Create new payment
      Merchant Website->>Checkout API: POST /v1/api/payment with CUSTOMER JWT token
      Checkout API-->>Merchant Website: new payment instructions

      Note left of Merchant Website: Fetch status of a payment
      Merchant Website->>Checkout API: GET /v1/api/payment/{paymentId} with CUSTOMER JWT token
      Checkout API-->>Merchant Website: payment info
      deactivate Merchant Website
   end

1. You can use MERCHANT token to create multiple sessions from the backend service. In order to obtain such token you need to authenticate using role = MERCHANT:

   AUTH=$(echo -ne "$USERNAME:$PASSWORD" | base64)
   
   curl --request POST https://{checkout-api-url}.altapaysecure.com/checkout/v1/api/authenticate \
     --header "Content-Type: application/json" \
     --header "Authorization: Basic $AUTH" \
     --data '{
               "role": "MERCHANT"
             }'
   

2. Then using MERCHANT token create checkout session by sending POST request on /v1/api/session, where you will get sessionId in response.
3. If you want to proceed with the checkout session on the frontend part, you should create one-time-use CUSTOMER token associated with sessionId with it:

   AUTH=$(echo -ne "$USERNAME:$PASSWORD" | base64)
   
   curl --request POST https://{checkout-api-url}.altapaysecure.com/checkout/v1/api/authenticate \
     --header "Content-Type: application/json" \
     --header "Authorization: Basic $AUTH" \
     --data '{
               "role": "CUSTOMER",
               "sessionId": "$SESSION_ID"
             }'
   

4. CUSTOMER token will be created in return giving you access only to this particular checkout session.
5. Pass CUSTOMER token to the web application to continue with finishing checkout and doing a payment
6. Later you can still use MERCHANT token to read sessions data from the backend service.

New token for each session + background processing token

You can go through payment flow using CUSTOMER token

sequenceDiagram
   participant Merchant Service
   participant Merchant Website
   participant Checkout API

   loop For every customer session
      activate Merchant Service
      Note left of Merchant Service: Create CUSTOMER token
      Merchant Service->>Checkout API: POST /v1/api/authenticate
      Checkout API-->>Merchant Service: CUSTOMER JWT token

      Note left of Merchant Service: Create a session
      Merchant Service->>Checkout API: POST /v1/api/session with CUSTOMER JWT token
      Checkout API-->>Merchant Service: session data
      deactivate Merchant Service

      Note over Merchant Service,Merchant Website: Pass JWT token to the Web App

      activate Merchant Website
      Note left of Merchant Website: Load a checkout session
      Merchant Website->>Checkout API: GET /v1/api/session/{sessionId} with CUSTOMER JWT token
      Checkout API-->>Merchant Website: session data

      Note left of Merchant Website: Create new payment
      Merchant Website->>Checkout API: POST /v1/api/payment with CUSTOMER JWT token
      Checkout API-->>Merchant Website: new payment instructions

      Note left of Merchant Website: Fetch status of a payment
      Merchant Website->>Checkout API: GET /v1/api/payment/{paymentId} with CUSTOMER JWT token
      Checkout API-->>Merchant Website: payment info
      deactivate Merchant Website
   end

while performing background processing on the backend service using MERCHANT token

sequenceDiagram
   activate Merchant Service
   Note left of Merchant Service: Create MERCHANT token
   Merchant Service->>Checkout API: POST /v1/api/authenticate
   Checkout API-->>Merchant Service: MERCHANT JWT token

   Note left of Merchant Service: Fetch status of a payment
   Merchant Service->>Checkout API: GET /v1/api/payment/{paymentId} with MERCHANT JWT token
   Checkout API-->>Merchant Service: payment info
   deactivate Merchant Service

1. You can use CUSTOMER (default) token for each session you're creating from the backend service:

   AUTH=$(echo -ne "$USERNAME:$PASSWORD" | base64)
   
   curl --request POST https://{checkout-api-url}.altapaysecure.com/checkout/v1/api/authenticate \
     --header "Content-Type: application/json" \
     --header "Authorization: Basic $AUTH" \
     --data '{
               "role": "CUSTOMER",
             }'
   

2. Then using CUSTOMER token create checkout session by sending POST request on /v1/api/session, where you will get sessionId in response.
3. Pass CUSTOMER token to the web application to continue with finishing checkout and doing a payment
4. If you want to fetch any information about your customer's payments in the future, you should issue MERCHANT token to proceed:

   AUTH=$(echo -ne "$USERNAME:$PASSWORD" | base64)
   
   curl --request POST https://{checkout-api-url}.altapaysecure.com/checkout/v1/api/authenticate \
     --header "Content-Type: application/json" \
     --header "Authorization: Basic $AUTH" \
     --data '{
               "role": "MERCHANT"
             }'
   

5. Then using MERCHANT token you can query all the data of your customers.