Our documentation site provides easy to follow steps to getting started with an Instance Issuance card program, conceptual overviews of topics such as transactions and funding, reference docs for our APIs. We aim to write detailed guides and thorough API and SDK docs, but if you can't find the information you're looking for, please email us at info@simplifipay.com.
Developers looking to start their integration with SimpliFi platform should:
Before getting started with testing your program in oura Ssandbox, let's take a moment to understand some of the key principles and definitions governing the SimpliFi APIs.
SimpliFi uses API keys to control access to our APIs. These keys consist of a public component and a private component, which act like a username and password. Keys would always be associated with either a Sandbox or production environment. Sandbox keys would not work in a production environments and vice versa.
With the SimpliFi API, information will flow from the SimpliFi platform to your backend. You can then pass it on to the cardholder’s mobile application (or use SimpliFi’s White Label app solution), with private API keys used to secure the communication. These API keys are a pair of values that you can generate in a portal.
Transient errors can happen, particularly where networking issues may be involved. The current best-practice on this is to use idempotency keys. We recommend reading Stripe's idempotency blog post to understand more about it.
You’d be able to send the same request multiple times to ensure that the action wont be repeated. To accomplish this simply add Idempotency-key header with a unique value to each Post/Put/Delete call.
The API version is indicated in each endpoint resource path. For example, https://dev-lb.simplifipay.com/v1/user/{uuid} indicates the API is at version 1. SimpliFi increments the version number when it releases a new version containing backwards-incompatible changes. Minor updates and bug fixes are typically released without incrementing the version number.
We use standard HTTP response codes for anything we write.
SimpliFi API whenever returns an error message it does so in Json format.
SimpliFi API supports sorting and pagination for most endpoints that return arrays of resources. The sorting mechanism places the resources in order; the pagination mechanism then returns a specific range of those ordered resources. You can control sorting and pagination by way of URL query parameters.
SimpliFi APIs are built around below main objects:
This is the entity that wants to issue cards with their brand. They would be clients to SimpliFi and SimpliFi would have a direct relationship with them.
A number of Card products are preconfigured with-in the SimpliFi environment to cater to the different use cases the a Corporation may have. For Sandbox only Corporate payout as a card product is available. In a live environment, a Corporation may choose one of the preconfigured card products or create a custom card product to fulfil its requirements. A typical card product may look as follows:
Each card product would have a variety of pre-configured controls associated with it. Controls can be divided into three broader categories:
These controls would determine the limits associated with a card depending on the nature of the transaction, the channels where the card is used and the time period during which the card is used. Each velocity control would have an identifier and can be set as default for that card product. Every card issued within the card product would inherit the default velocity control. A new velocity control may be configured for a card product, however, this functionality is only available in the production environment. A typical Velocity control may look as follows:
These controls determine which channels (i.e. POS, ATM, Online, International etc) where the card can be used at. Similar to velocity control, each authorization control would have an identifier and one of them could be set as a default for a card product which would be inherited by each card issued within that card product. For Sandbox the possible authorisation controls would be a binary choice across online, POS ATM and International transactions.
These controls provide the ability to block cards from being used at certain merchants, Merchant categories or groups of merchant categories. In production environment, depending upon restrictions imposed by regulators and/or issuing banks, certain merchant categories would remain in the blocklist permanently, however the Corporation could add additional merchant categories in the blocklist (or alternatively remove self added merchants/merchant categories from the blocklist).
A user is an entity within the SimpliFi platform. Know Your Customer (KYC) is performed against each user (as required by regulations) and KYC information is stored for each user. On the SimpliFi platform, every user needs to be associated with a Corporation. A user can not be a stand alone object without a relationship with a Corporation.
The card is an externally-facing payment instrument, either in virtual or physical form, that is used to interact with funds stored as a balance on the card. All SimpliFi cards are tied to a balance account. Cards would inherit characteristics and rules for the card product to which they belong, however, certain features of the cards (i.e. controls) can be defined and controlled at the card level. SimpliFi is able to support multiple cards per corporation.
Payments made by a user with their card as well as other transaction events such as refunds. In general, for a transaction to be authorized, the associated card must have sufficient balance to cover the transaction amount.
This represents the balance of funds associated with and accessed by a given card. SimpliFi is able to support multiple balances per corporation.
We also provide the ability to support the ledger maintenance at the corporation end.
The SimpliFi platform was designed to help you quickly prove out a concept and/or experiment with new card products. We’re excited about what you and the community of developers will build using the turnkey Instant Issuance program and we’re here to support you through this journey.
Things you'll need to get going:
However, if terminals and cURL are alien to you, then Postman is a much-loved API testing tool (all our YouTube tutorials are performed using it).
To create an account with SimpliFi, we ask you to provide your name, the name of your company, your company URL, country and your work email address. After you verify your email address, you’d be receiving the login credentials of our portal which would have the Sandbox access keys.
When you first login to SimpliFi, you will be directed to the SandbBox environment. Sandbox is a replica of our production environment, where you can simulate our offerings irrespective of your PCI-DSS compliance status. You can:
You can create a user, by providing their PII information as well as internal identifiers of the users in your corporation.. Every user by default is linked with a card product. In a production environment, the card product will be set up when we onboard you. If there are multiple card products that are set up for a corporation, those can be used during the card issuance process for the user. However, in a simulated environment, there is one pre-configured card product available which would be applied by default and the cards issued for the users would inherit characteristics of that card product. A user would follow below lifecycle
For a corporate funded program, the responsibility of completing the KYC sits with the corporation.. The type of the KYC needed for a card program would depend upon the issuer, country and the card product being considered. In a simulated environment, we have provided a simple KYC set up where the corporation would upload the user document (Passport or National ID document). In the production environment, the uploaded document information would be verified with entered details to adjudicate successful KYC where SimpliFi would use OCR to fetch the details on the card. The user information would also be checked with AML/PEP/CTF databases. However, in the simulated environment, we have written a worker to provide a happy path and thus any uploaded document would be auto approved.
On SimpliFi platform, the cards can be issued by a corporation within their activated card product to a user. Once a card is issued it would be pre configured in the card product whether a card is virtual/physical, regular/disposable etc. Also initial balance on the card can be configured through APIs. In the Sandbox by default, the activated card product is configured to be virtual and with zero balance. However, these could be reconfigured through APIs. Once the card is issued, it is ready to be provisioned to the user it belongs to either virtually or in physical form using our card production and delivery partners.
Issuance of the card doesn’t mean that the card is ready to be used. The steps of issuance and activation are included to provide more controls to corporations in case they want to accomplish the issuance and activation steps through a maker checker concept or to pre-issue a batch of cards in advance and activate individual cards in future and different time. Once a card is activated, it is ready to be used by the end user. SimpliFi can support provisioning the card to its Whitelabel app solution or the corporation can choose to deliver it to its users on any other corporation managed app.
Every corporation on the SimpliFi platform would need to fund the card product through a bank account. Corporations can load/unload any card product with appropriate balances onto a master account. Once a card is loaded, the balance from the master account is debited and a corresponding credit is made to the card. In a Sandbox environment, loading and unloading of the card by the corporation is possible, however, this functionality may vary depending upon the card product set up in the production environment. In the Sandbox environment, SimpliFi would add a dummy balance of 10,000.00 to the activated card product for the corporation to use.
SimpliFi provides APIs to manage the transition of the card depending upon use cases as below:
SimpliFi uses API keys to control access to our APIs. Keys consist of a public component and a private component, which act like a username and password.
You can create new sandbox keys to test out the APIs.
To generate API keys: