Business cards

API docs: api.mobilum.com

Authentication: HMACSHA256 Authentication

Overview

This system is designed to manage corporate card transactions based on a master corporate balance. It introduces a structure where approvals are issued against the corporate balance to allocate specific budgets for card usage.

Key Concepts

  • Corporate Balance: A centralized pool of funds managed by the organization.

  • Approval: A budget authorization linked to a specific card, representing a portion of the corporate balance that can be used for transactions.

  • Card Assignment: Each approval is tied to a single card and user. Card data remains constant across approval changes.

  • Approval Lifecycle: Any modification to an approval (e.g., budget change, PIN update) results in the creation of a new approval instance. The new instance retains the same card association but reflects updated parameters. The original approval is considered closed or replaced.

Approval Statuses

The lifecycle of an approval involves several statuses that reflect the current state of the approval request and its usage. These statuses are key to understanding how approvals move through the system from creation to expiration.

CREATED

Occurs only when a user requests changes on a reapproval.

ACCEPTED

Assigned when an approval is initially created. It transitions to the DELIVERED status after registration is completed.

CANCELED

Indicates that an approval or reapproval in status CREATED, ACCEPTED, or PREPARED has been canceled by the corporation.

REJECTED

Assigned when a reapproval in the CREATED status is rejected by the corporation.

EXPIRED

Assigned when a reapproval in CREATED status is neither accepted nor rejected before expiration.

PREPARED

The approval has been ACCEPTED and is waiting for card generation. The card is generated on the validFrom of the approval.

DELIVERED

Indicates the card has been issued. This is the active state in which card transactions can occur.

FINISHED

The approval was in DELIVERED status and has now exceeded the end date of its assignment.

REAPPROVED

A reapproval has been created for an existing approval that is currently in ACCEPTED or DELIVERED status.

LOCKED

(Card status) This is a status of the card, not the approval itself. However, it is shown in the approval flow to indicate that a card can only be locked or unlocked when the related approval is in the DELIVERED state.

Basic Flow

skinparam monochrome true participant App participant API ==Create user== App -> API : POST /corporates/users \n //name, lastName, email, phone// return //user// ==Create card== App -> API : POST /corporates/corporates/{corporateUuid}/approvals \n //userUuid, budget, validTo, validFrom// activate API API --> App : //approval// API -> API : Issuing a card App -> API : GET /corporates/{corporateUuid}/approvals/{approvalUuid} return //approval & card// deactivate API ==Get card data== App -> API : GET /corporates/{corporateUuid}/users/{userUuid}/approvals return //approvals// App -> API : GET /corporates/{corporateUuid}/approvals/{approvalUuid}/details \n //public key// return //encrypted card details// ==Deposits== App -> API : GET /corporates/{corporateUuid}/deposits return //deposit addresses// App -> App: Deposit App -> API : GET /corporates/{corporateUuid}/top-ups return //top-ups// App -> API : POST /corporates/{corporateUuid}/approvals/{approvalUuid}/increase-budget \n //additionalBudget// return //reapproval//