• About
  • Products
  • Solutions
  • Resources
    • Developers Guide
    • Api Reference
  • Request a Demo
Try Portal
Getting Started Welcome SimpliFi Architecture
Understanding API Resources Getting API Keys
Understanding SimpliFi APIs
API authentication Idempotency Versioning Response Codes
HTTP Status Codes Error Messages
Sorting & Pagination
API Objects Testing the program in SandBox
Basics Creating your developer account
SandBox
Getting sandbox keys Creating Core API keys
Webhooks in SimpliFi Platform Enumerations iOS SDK Android SDK

Understanding the basics of SimpliFi platform

Welcome to SimpliFi platform! We are excited that you have taken the time to understand how the SimpliFi platform works, so let's start by going through some of the basic concepts of data types, API and Webhook structure and default parameters, etc.



1. General Information

This chapter includes general information related to the documentation in SimpliFi.



1.1. Data Type Structure

The requests and responses of APIs listed in this document contain fields of multiple data types. They include both standard and custom developed data types. The table below lists the data types, along with their brief description.


Data Type Description
Standard Data Types
Int This data type indicates Integer values.
String This data type indicates String values. Example: The UUIDs and other alphanumeric fields with indefinite lengths are of this data type.
Number This data type indicates big decimal values. Example: The amount fields with probability of storing up to three decimal points are of this data type.
ENUM with String value This data type indicates enumeration with String values as its elements. Example: Enum field “requestStatus” has 2 allowed values. “SUCCESS” and “FAILURE”
Object This data type indicates a collection of fields, containing sub-fields. The object fields are represented in the following format: Object Name.Subfield. Example: userDetail.address
Array of Objects This data type indicates an array of objects.

Custom Data Types
Date The SimpliFi platform stores dates in the following format: "yyyy-mm-dd hh:mm:ss”
String The SimpliFi platform stores phone numbers in the following format: + sign, followed by a country code (0-3 digits), followed by the mobile number of the cardholder. Example: “+971509059537”
Currency The SimpliFi platform follows ISO 4217 currency codes. For example “USD”, “AED" etc.
Country The SimpliFi platform follows ISO 3166-1 Alpha3 country codes. For example, “ARE” , “USA”, “PAK” etc.


1.2. Request Structure

The cURL structure for all the GET calls follows the pattern given in the following example:

                curl --location --request GET 'https://uat-lb.simplifipay.com/v1/card-program/card-control/{uuid}?cardProgramUuid=[cardProgramUuid]'
                

Where, the value for all the query parameters (cardProgramUuid in this case) is to be provided as per the format, during the API integration.


Important
All the path parameters are mandatory and the query parameters are optional.


1.3. Default State for Async APIs

The SimpliFi platform marks all the asynchronous APIs such as Activate a Card, Load a Card, and Unload a Card etc. as PENDING by default. The webhook response of these API calls declares them as SUCCESS or FAILURE on runtime.




1.4. Default Parameters Type

The SimpliFi platform marks all the parameters as Body Parameters unless they are specifically marked as Path Parameter, Query Parameter, or Header Parameter in the field description grid.




1.5. Webhook Structure

As a standard procedure, all the asynchronous API calls that are made using the endpoints published by the SimpliFi platform, return a webhook. The purpose of these webhooks is to inform the API user about the status of the endpoint that was initiated. The webhook structure remains the same in all the asynchronously running API calls with the only difference in ‘eventType’ field and ‘eventPayload’ object. These two fields are unique for every webhook response, describing for what event type the webhook was generated and what was the payload for that event.


Given below is a generic webhook structure that is coupled with the two unique fields for all the successful asynchronous API calls:

                
                   "{
                      "uuid": "",
                      "requestUuid": "",
                      "companyUuid": "",
                      "requesterUuid": “",
                      "requestStatus": "SUCCESS",
                      "eventType": "",
                      "eventPayload": {
                      },
                      "errorCode": null,
                      "errorMessage": null,
                      "sourceErrorCode": null,
                      "sourceErrorMessage": null,
                    }"
                
                
Field Data Type Mandatory/Optional Description
uuid String Mandatory This field contains a unique identifier for the webhook.
requestUuid String Mandatory This field contains a unique identifier of the request received in the header.
companyUuid String Mandatory This field contains a unique identifier for the company.
requesterUuid String Mandatory This field contains a unique identifier for the user who has requested the process.
requestStatus ENUM with String value Mandatory This field contains the current status of the request. The two possible values are “SUCCESS” and “FAILURE”.
eventType Object Mandatory This field contains the event of the request which is different for every API call.
eventPayload Object Conditional (If the response is in 200 series, the eventPayload is mandatory. Otherwise, it may not be produced.) This field contains the unique eventPayload.
errorCode Number Mandatory This field contains the error code, if any. This field is mandatory if the requestStatus is FAILURE.
errorMessage String Mandatory This field contains the error message. Refer to the Error Codes section for better understanding of errors. This field is mandatory if the requestStatus is FAILURE.
sourceErrorCode String Mandatory This field contains the source error code, if requestStatus is FAILURE.
sourceErrorMessage String Mandatory This field contains the source error message, if requestStatus is FAILURE.

1.5.1. Exception

There is an exception for the “Transaction Push Webhook”. It is a webhook that is to be hosted by the SimpliFi clients in order to keep their transactions in sync with the SimpliFi platform. Once successfully hosted at the client side, this webhook is generated on every transaction to keep all the stakeholders aware of all the transactions.



1.6. RequestUuid

A unique RequestUuid is required to be passed as part of the header whenever a SimpliFi API is called from your system. This would us in debugging in case of a discrepancy in the expected behavior of the API.


Welcome

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:

  • Request access to our portal by registering on our website. By registering here the developers would get access to our no code platform i.e. SimpliFi Portal as well as authentication keys to test the APIs in a sandbox environment.
  • Explore our APIs which would provide ever evolving list of our APIs

SimpliFi Architecture

SimpliFi uses Async architecture to let the clients use its APIs in a modular set-up. Every API call made to SimpliFi would result in response code 200 if the request was successfully received. Once the request is received it gets handled internally to get it processed.

Once the request is processed the response of the request is provided to the clients at their configurable endpoints through webhooks. Webhook body would provide appropriate values in case the request was completed as well as error codes in case the request resulted in failure.

There are 5 attempts made to deliver the webhooks to the end points. Even if the delivery of the webhooks fails the same information can be accessed by clients using APIs.

Understanding API Resources

CardProduct: This is the highest level of the resource hierarchy with-in SimpliFi platform. CardProducts are implemented at the partnering processors depending upon client requirements and approvals from regulatory bodies and schemes. CardProduct implementation once completed would return a CardProgramTemplateUUID which can be used to create card programs.

Funding Source: Every client (or company i.e. client of SimpliFi client) would get a dedicated funding source in each approved currencies for Cardproduct. One funding source can be linked with multiple Cards Products or card programs. Funding source is the Account number that is created to specifically run the card programs created under a Company.

CardPrograms: These are configured templates and define the unique use case per client. These can also be configured and provided dedicated names to identify unique company in case the SimpliFi client is not the end client issuing the cards to its customers. Any client can have multiple Card program using the same template (product type) or different template (product type).CardPrograms have below segments:

  • CardTemplate: This aspect of CardProgram captures those variables which are expected not to change in the medium to long run. These variables include information like Issuing bank, currencies, card limits, Program type (corporate/consumer funded, corporate/consumer owned), Scheme, markets, fees etc.

  • CardControls: SimpliFi provides a multi faceted control structure to its clients. Any number of card controls can be pre configured under a card product and can be accessed through APIs. These card controls can be applied at card group level as well as individual card level and can be changed during any time of the card lifecycle. It categorizes controls in to three broader flavors:

    • Authorization controls: Authorization controls define the channels on which the cards can be used.These are binary controls and can be configured to be either allowed or not-allowed. Channels could be Online Usage, POS Usage, ATM Usage, Cross Border, Cross currency usage etc

    • Velocity Control: Velocity controls define usage in rolling windows across the channels. These are the settings which can be established at transaction, daily, weekly, monthly or any customized time period across channels. Any number of velocity controls can be pre configured and could be invoked using APIs

    • Merchant Controls: Merchant controls are the third layer of the controls which provides a capability to put any of the merchant category (MCC ID) or merchant ID in blocklist or allowlist. This is a powerful control which can be used to make any open loop card into restricted usage thus making it restricted loop cards.

  • Users: Users are cardholders to whom the cards would be issued. Users can be created using APIs. At the time of user creation; users are assigned under a card program. During card issuance for the users the cardprogram can be overwritten by providing a different card program as an input. If card program as an input during card issuance is not provided then the default card program used during user creation can be used

  • Cards: These are payment cards which can be issued in virtual or physical form and can be used to conduct transactions. One user can have multiple cards

  • Wallets/Currencies: SimpliFi Support multi currency environment. Currently the SimpliFi platform supports 11 currencies. If the card requires more than one currency on the card, a dedicated wallet would be created supporting each currency.

    This document provides APIs to manage the above resources. SimpliFi also provides below tech resources to manage end to end card program.

  • PCI DSS Compliant SDK - Both iOS and Android SDKs which can be wrapped under client App to enable cardholders access their card details on the app. The SDKs can be integrated using the integration document (here). If the client card product would require the cards to be tokenized to be used across OEM Pay i.e. ApplePay/GooglePay/AndroidPay etc the same can be supported (subject the availability of such programs in the target market and simpliFi Partner). SimpliFi would also be able to provide Push provisioning of the Card to requested OEMpays.

  • Transactions: Transactions on SimpliFi platform could be accessed using two mechanisms:
    • getTransactions: The API can be called to see all the transactions at Card,user or cardprogram level. However this API would not be enough to update the client system with real time transactions
    • Transaction Webhook: To support clients update their system with real time transactions (which the cardholders be conducting outside of their system), SimpliFi would send

Getting API Keys

To request API keys for the SimpliFi platform please place a request here. Once we receive your request we’d be able to send you:

  • Client ID
  • User ID
  • Temporary Password
  • Dummy funding source in USD currency
  • CardprogramtemplateUUID

You’d be able to use the first three credentials to start testing APIs (or access SimpliFi Portal). You’ be able to use the dummy funding source to link it with the card programs you’d have created. We’d also be setting up a cardprogramtemplateUUID for you to start creating a card program. APIs can be run using your own postman environment or using SimpliFi sandbox with-in the SimpliFi portal (under developer section).

Getting Started

Understanding SimpliFi APIs

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.

API authentication

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.

  • Public key: These may be known to others
  • Private key: It's your own secret key. Please keep it safe and the same can be used to access SimpliFi APIs in combination with a public key

Idempotency

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.

Versioning

The API version is indicated in each endpoint resource path. For example, for UAT https://uat-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.

Response Codes

HTTP Status Codes

We use standard HTTP response codes for anything we write.

  • Codes in the 2xx range typically indicate success.
  • Codes in the 4xx range typically indicate an error in the request.
  • Codes in the 5xx range typically indicate an error at the SimpliFi platform
  • status codes table

Error Messages

SimpliFi API whenever returns an error message it does so in Json format.



Error Code Error Message
0 "Global Success"
64001 "External Merchant Source Configuration Not Found"
63002 "KYC Not Found"
20001 "First name null or empty"
20002 "First name does not match with regex"
20003 "Middle name null or empty"
20004 "Middle name does not match with regex"
20005 "Last name null or empty"
20006 "Last name does not match with regex"
20007 "Invalid gender"
20008 "DOB null or empty"
20009 "DOB is future date"
20010 "DOB does not match with regex"
41002 "NECP Processor Error"
20011 "Email null or empty"
41003 "NECP Product Detail Already Exists"
20012 "Email does not match with regex"
41004 "NECP Product Detail Not Found"
20013 "Email already exist"
41005 "Failed to Encrypt Data"
20014 "MSISDN null or empty"
41006 "Failed to Decrypt Data"
20015 "Mobile number is invalid. Please provide a valid mobile number and submit the form"
41007 "The binary key or input text cannot have an odd number of digits"
20016 "MSISDN already exist"
20017 "Username null or empty"
62001 "Country Not Found"
20018 "Username does not match with regex"
62002 "Currency Code is Invalid"
20019 "Username already exist"
20020 "Card program null or empty"
20022 "Country code null or empty"
20023 "Country code invalid"
20024 "Street address null or empty"
20025 "Street address does not match with regex"
20026 "State code null or empty"
20027 "State code invalid"
20028 "City code null or empty"
20029 "City code invalid"
20030 "Postal code null or empty"
20031 "Postal code invalid"
20032 "User role not valid"
20033 "Create user failed"
20034 "Update user failed"
20035 "Update user status not allowed"
20036 "Update user email is not allowed"
40004 "Card Control Missing"
20037 "Update username is not allowed"
40005 "Configuration Missing"
20038 "Contact is null or empty"
40006 "Card Program UUID Missing"
40007 "Card Template UUID Missing"
20040 "Invitaiton token expired"
40008 "Velocity Control Missing"
20041 "Invitation token already exists"
61001 "Task Not Found"
40009 "POI Missing"
20042 "Invalid JWT signature"
61002 "Task can not be updated with the same status"
40010 "Invalid Card Program UUID"
20043 "Invalid JWT token"
61003 "Checker Not Found"
40011 "Velocity Control List Missing"
20044 "Expired JWT token"
61004 "Checker Event Not Found"
40012 "Velocity Adapter Key Missing"
20045 "Unsupported JWT token"
61005 "Invalid Customer Title or Length Longer Than 25 Characters"
40013 "Card UUID Missing"
20046 "User not found"
40014 "ATM Missing"
20047 "Failed To Change User Status"
40015 "POS Missing"
20048 "Invalid JWT token"
40016 "Ecommerce Missing"
40017 "Merchant Controls Missing"
20050 "Document null or empty"
40018 "Name Missing"
20051 "Document is invalid"
40019 "Master Account Token is Missing"
20052 "KYC document already exists"
40020 "White List Missing"
20053 "OTP is Invalid"
40021 "White List Name Missing"
20054 "Required field user status must be SUSPEND or ACTIVE or INVITATION_EXPIRED or BLOCK"
40022 "Black List Missing"
20055 "Users with role ADMINISTRATOR or CUSTOMER can't be updated"
40023 "Black List Name Missing"
20056 "User Detail Not Found"
40024 "Adapter Key Missing"
20057 "User Address Not Found"
40025 "Currency Missing"
20058 "User Contact Not Found"
40026 "Adapter Program Code Missing"
20059 "User Invite Token Not Found"
40027 "Scheme Missing"
20060 "User not found against provided identifier"
40028 "Issuer Country Missing"
20061 "Identifier Type is missing"
40029 "Card Program Details Missing"
20062 "Phone Number Country code not found for given number"
40030 "Authorization Group Missing"
20063 "User can not be created A card holder already exists"
40031 "Invalid Authorization Group"
20064 "User can not be created A team member already exists"
40032 "Authorization Group Key Missing"
20065 "User Can not be invited"
40033 "Authorization Group Value Missing"
60001 "Given event type is not a valid event"
20066 "Country code is missing"
40034 "MVC Group Missing"
60002 "Required field url must not be null or empty"
40035 "MVC Authorization Adapter Key Missing"
60003 "Invalid url"
20067 "User can not be deleted user has Active Card(s)"
40036 "MVC Velocity Adapter Ker Missing"
60004 "Required field name must not be null or empty"
20068 "Card can not be enabled active user not exists"
40037 "Limit Missing"
60005 "Invalid name"
40038 "Frequency Missing"
60006 "Invalid value"
20071 "User Not Found In IDP"
40039 "Transaction Details Missing"
60007 "Invalid length"
20072 "IDP User Conflict"
40040 "Transaction Detail Type Missing"
60008 "Event type already exists"
81001 "Sms config not found"
20073 "Role Not Found in IDP"
40041 "Transaction Detail MIN Missing"
60009 "Webhook not found"
20074 "Cannot able to parse given phone number"
40042 "Transaction Detail MAX Missing"
60010 "Request audit log not found"
81003 "Config null or empty"
20075 "Contact already exist"
40043 "White List Adapter Key Missing"
60011 "Webhook audit log not found"
81002 "Sms config with given company id and country code already present"
40044 "White List Merchants Missing"
60012 "Webhook already exists"
81005 "Country code null or empty"
40045 "Black List Adapter Key Missing"
60013 "Request audit log already exists"
81004 "Provider null or empty"
40046 "Black List Merchants Missing"
60014 "Webhook audit log already exists"
81007 "Token null or empty"
40047 "MID Missing"
60015 "Webhook Gateway Exception"
81006 "Apps id null or empty"
40048 "Card Validity Missing"
81009 "EventType doesn't match any Events"
40049 "Invalid Card Validity"
81008 "Event Type null or empty"
40050 "Invalid Card Program Velocity Adapter Key"
81011 "NotificationType doesn't match any Notification Types"
40051 "Invalid Card Control Velocity Adapter Key"
81010 "Notification Type null or empty"
40052 "Third Party ID Missing"
81013 "Notification event config does not exist"
40053 "Funding Source Exists"
81012 "Notification event config already configured"
40054 "Card Program is not Active"
40055 "Card Control Not Found"
40056 "Card Program Template Not Found"
40058 "External Merchant Source Missing"
40059 "External Merchant Source Provider Missing"
40060 "External Merchant Source Params Missing"
40061 "FIDEL Location ID Missing"
40062 "FIDEL API Key Path Missing"
40063 "FIDEL API Key Path Already Exists"
40064 "Load Merchants From External Source Missing"
80001 "Public Token is missing"
40065 "Name Already Exists"
80003 "Data field is missing"
40067 "Invalid Amount"
80002 "Transaction Id is missing"
40068 "Attachment Missing"
40069 "Transaction Type Missing"
80004 "Transaction Response is Invalid"
40070 "Invalid Funding Source Currency"
40071 "Company uuid null or empty"
40072 "Adapter key null or empty"
40073 "Parent Account Id null or empty"
40074 "Currency null or empty"
40075 "Profile Id/Adapter Code null or empty"
40076 "Product Id null or empty"
40077 "Invalid adapter key"
40078 "Invalid currency"
40079 "Parent Account Id already exists"
40080 "Processor mapping not found"
40081 "Card Program status can not be changed"
40082 "Card Program Template Name Already Exist."
40083 "Card control already exists on this card"
15001 "Company Record already exists"
15002 "Company not found"
15003 "Company Theme Details Record already exists"
99997 "General Error"
15004 "Company Theme Detail not found"
15005 "Company Theme Status Change failed"
99999 "Undefined Response"
15006 "Email or Username already exists"
99998 "Internal System Error"
15007 "Company not found in cache"
35001 "Transaction Not Found"
35003 "Permission Not Allowed"
35004 "Date null or empty"
35005 "Date Parsing Error"
35006 "Start date invalid"
35007 "End date invalid"
35008 "Date range invalid"
35009 "Page size invalid"
35010 "The Card is Already Blocked"
35011 "Card Expiry Date is Invalid"
32002 "Product Detail Not Found"
32003 "Source Account Not Found"
32004 "Destination Account Not Found"
32005 "The response is empty"
32006 "Unable to parse Necp Response"
32007 "Invalid Card Type for NECP"
32008 "Card account not found"
32009 "Card not ready to set PIN"
32010 "Wrong OTP"
10001 "Invalid Input"
10002 "Invalid Fields"
10003 "Required Field Missing"
10004 "All Fields Are Null"
10005 "Entity Not Found"
10006 "Request Timeout Error"
10007 "Resource Not Found"
10008 "Duplicate Request Error"
10009 "Service Down Error"
10010 "Service Timeout Error"
31002 "GPS Processor Error"
10011 "Processor Down Error"
10012 "Processor Timeout Error"
10013 "Processing Error"
10014 "Marshall Exception"
10015 "Unmarshall Exception"
10016 "Authorization Error"
10017 "Number Format Exception"
10018 "Parse Exception"
10019 "Copy Exception "
10020 "Log entity not found"
10021 "Invalid Parameter"
10022 "Simplifi Gateway Exception"
10023 "IP not whitelisted"
10024 "Invalid header"
30001 "Card Already Activated"
30002 "Card Already Exists"
30003 "Card Program Not Found"
30004 "Card Not Found"
30005 "Checker Request Not Found"
30006 "Card Not Yet Issued"
30007 "Card Still Active"
30008 "Card Not Active"
30009 "Master Card Not Setup Yet"
30010 "Only the cards having Locked status can be changed to Active "
30011 "KYC Not Completed"
30012 "Card Program Uuid is Null or Empty"
30013 "User Uuid is Null or Empty"
30015 "Request Amount is Null or Empty"
30016 "Request amount exceed the card balance"
30017 "GPS API Unavailable"
30018 "Date Range is Invalid"
30019 "Invalid Page Number Provided"
30020 "Invalid Page Count Number Provided"
30022 "Funding Source Not Found"
30023 "Date Range is Invalid"
30024 "Card is already in the required status"
30025 "Only Active Cards can be changed to Locked or Disabled Status"
30026 "Card load log already exists"
30027 "Card load log already exists"
30028 "Funding Source Not Found by card program"
30029 "Request Uuid Already Exists"
30030 "funding source not configured for the card program"
30031 "Only physical card can set pin"
30032 "Pin length should be 6"
30033 "only numeric is allowed in pin"
50001 "Document Not Found"
30034 "Only cards with ISSUED status are eligible for otp generation"
30035 "Only cards with ACTIVATED status are eligible for change PIN otp regeneration"
30036 "Only cards with ACTIVATED status are eligible for conversion"
30037 "Only cards with ISSUED status are eligible for otp verification"
50005 "Upload File Missing"
30038 "OTP Verification Failed"
50006 "Upload File Not Found"
50007 "Unable To Read File"
71001 "BulkFile Entity was not found for uuid %s"
50008 "File Size is Invalid"
70001 "Insufficient-funds"
70000 "Not-Honoured"
70003 "Frequency-limit-exceeded"
70002 "Transaction-not-allowed"
70005 "Fraud"
70004 "Card-closed"
70007 "Card-stolen"
70006 "Card-lost"
70009 "Invalid-publicToken"
70008 "Invalid-issueCode"
70011 "New Product Id Missing"
70010 "Invalid-card-design"
70013 "Invalid-renewal-expiry"
70012 "Card-renewal-inprogress"
70015 "Invalid-payment-usage-group"
70014 "Invalid-balance"
70017 "Invalid-virtual-card-image"
70016 "Invalid-delivery-method"
70019 "Invalid-productId"
70018 "Invalid-processor request id"
70021 "Invalid-load-source"
70020 "Invalid-groupType"
70023 "Invalid-issueCode"
70022 "Processor request Id Missing"
70025 "Invalid-authType"
70024 "Invalid-txnCode"
70027 "Invalid-locTime"
70026 "Invalid-locDate"
70029 "Invalid-CVV"
70028 "Invalid-publicTokenOrPANOrDesign"
70031 "Invalid-CityOrPostCode"
70030 "Invalid-AccCode"
70033 "Invalid-LoadFee"
70032 "Invalid-LoadFundType"
70035 "Invalid-Title"
70034 "Invalid-LoadedBy"
70037 "Invalid-limit-group"
70036 "Reason Missing"
70039 "Invalid-CardName"
70038 "Invalid-usage-group"
70041 "Invalid-EndDate"
70040 "Invalid-StartDate"
70043 "Authentication-failed"
70042 "Invalid credentials"
70045 "Processor Error"
70044 "Invalid-product configuration"
70047 "Application Status is Invalid"
70046 "Invalid Header"
70049 "Unable to parse csv file"
70048 "Physical card already issued"
66001 "Role Creation Failed"
66002 "Failed To Fetch Role"

Sorting & Pagination

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.

API Objects

SimpliFi APIs are built around below main objects:

  1. Company

    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.

  2. Card Products

    A number of Card products are preconfigured with-in the SimpliFi environment to cater to the different use cases the a Company may have. For Sandbox only Corporate payout as a card product is available. In a live environment, a Company 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:

  3. Each card product would have a variety of pre-configured controls associated with it. Controls can be divided into three broader categories:

    1. Velocity Control

      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:

    2. Authorization Control

      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.

    3. Merchant Blocklist

      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 Company could add additional merchant categories in the blocklist (or alternatively remove self added merchants/merchant categories from the blocklist).

  4. Users

    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 Company. A user can not be a stand alone object without a relationship with a Company.

    create users
  5. Cards

    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 company.

  6. Transactions

    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.

  7. Balance account

    This represents the balance of funds associated with and accessed by a given card. SimpliFi is able to support multiple balances per company.


We also provide the ability to support the ledger maintenance at the company end.

Testing the program in SandBox

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.

Basics

Things you'll need to get going:

  • A terminal (such as: Terminal for MacOS, Command Prompt for WindowsOS, konsole, gnome-terminal, or iTerm2).
  • cURL (it's probably already installed — but if not use your package manager).

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).

Creating your developer Account

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.

SandBox

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:

  1. Create Users

    You can create a user, by providing their PII information as well as internal identifiers of the users in your company. 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 company, 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

  2. Complete the KYC by uploading relevant document(s):

    For a corporate funded program, the responsibility of completing the KYC sits with the company. 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 company 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.

  3. Issuance of the Card

    On SimpliFi platform, the cards can be issued by a company 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.

  4. Activation of the Card

    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 company 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 company can choose to deliver it to its users on any other company managed app.

  5. Loading and unloading the card

    Every company on the SimpliFi platform would need to fund the card product through a bank account. company 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 company 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 company to use.

  6. Manage Card Transition:

    SimpliFi provides APIs to manage the transition of the card depending upon use cases as below:

    • Report Card: This functionality is available to counter complaints related to compromised cards. When a card is reported, the existing PAN is disabled and a new card is issued for the user with the same balance as it was in the disabled card.
    • Replace Card: This functionality is used when the card is replaced either because the original card is expired or damaged.
    • Lock Card: This is used in case the customer or company wants to lock the card temporarily.
    • Deactivate Card: This is used to close the card account when the user is no longer associated with the company.

Getting Sandbox keys

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.

Creating Core API keys

You can create new sandbox keys to test out the APIs.

To generate API keys:

  1. Open the SimpliFi developer dashboard and navigate to the Developer section
  2. From the API Keys tab, select Add
  3. Store your API key and API secret in a safe place. The API secret will not be available again
  4. Select Done

Webhooks in SimpliFi platform

All the asynchronous API calls that are made using the endpoints published by the SimpliFi platform, return a webhook. The purpose of these webhooks is to inform the API user about the status of the endpoint that was initiated.

The webhook structure remains the same in all the asynchronously running API calls with the only difference in ‘eventType’ field and ‘eventPayload’ object. These two fields are unique for every webhook response. ‘eventType’ describes the event for which the webhook was generated and ‘eventPayload’ describes the payload for that event.


Sample Webhook structure in SimpiFi platform:

      
        {
          "uuid": "",
          "requestUuid": "",
          "companyUuid": "",
          "requesterUuid": “",
          "requestStatus": "SUCCESS",
          "eventType": "",
          "eventPayload": {
        },
          "errorCode": null,
          "errorMessage": null,
          "sourceErrorCode": null,
          "sourceErrorMessage": null,
        }
      
        

Field

Data Type

Mandatory/Optional

Description

uuid

String

Mandatory

A unique identifier for the webhook

requestUuid

String

Mandatory

A unique identifier of the request, received in the header.

companyUuid

String

Mandatory

A unique identifier for the company.

requesterUuid

String

Mandatory

A unique identifier for the user who has requested the process

requestStatus

ENUM with String value

Mandatory

Shows the current status of the request. The two possible values are “SUCCESS” and “FAILURE”

eventType

Object

Mandatory

Shows the event of the request which is different for every API call.

eventPayload

Object

Conditional (If the response is in 200 series, the eventPayload is mandatory. Otherwise, it may not be produced.)

Contains the eventPayload which is different for every API call.

errorCode

Number

Mandatory

Returns the error code, if any. This field is mandatory if the requestStatus is FAILURE

errorMessage

String

Mandatory

Displays the error message. Refer to the “Error Codes” section for better understanding of errors. This field is mandatory if the requestStatus is FAILURE

sourceErrorCode

String

Mandatory

Shows additional details, if requestStatus is FAILURE

sourceErrorMessage

String

Mandatory

Shows additional details, if requestStatus is FAILURE


List of Events in SimpliFi:

Below are the list of events in SimpliFi platform to which client developers can subscribe to receive the relevant information. Client developers should have the credentials of the SimpiFi Portal created for their company to select and subscribe to the webhooks.

*If you do not have the credentials to log into SimpliFi Portal, please reach out to your Company’s Client admin to get access to SimpliFi Portal.



Card Program events:

  • CARD_PROGRAM_CREATION

  • CARD_PROGRAM_UPDATION

  • RAISE_FUNDING_SOURCE



Card Holder events:

  • CARD_HOLDER_CREATION

  • CARD_HOLDER_UPDATION

  • CARD_HOLDER_DELETION



Card events:

  • CARD_ISSUANCE

  • CARD_ACTIVATION

  • CARD_LOAD

  • CARD_UNLOAD

  • CARD TYPE CHANGE

  • CARD_STATUS_CHANGE



Portal User Invite:

  • USER_INVITE



CARD_ISSUANCE

Cards are issued to cardholders that are created under a card program. Once a card issue event is successful then the webhook response is posted on the designated url used while adding this webhook through SimpliFi Portal.

Below is the sample webhook response for the same.



Webhook Response
      
        {
          "eventType": "CARD_ISSUANCE",
          "eventPayload": {
          "expiryDate": "06/23",
          "userUuid": "b23b0375-d321-4c26-8c64-8135dac456bb",
          "cardUuid": "67eed9e3-f639-4e2f-ba15-e934ff3fcf56",
          "maskedPAN": "************7825",
          "cardStatus": "ISSUED",
          "requestUuid": "d5c0ed60-d3d8-42a7-b4cd-a27c4d4c022c"
        }
        }
      
      


CARD_ACTIVATION

Cards are activated once they are issued successfully. After the card is successfully activated then the webhook response is posted on the designated url used while adding this webhook through SimpliFi Portal.

Below is the sample webhook response for the same.



Webhook Response
        
          {
            "eventType": "CARD_ACTIVATION",
            "eventPayload": {
            "userUuid": "60978921-7000-4f2e-884c-0423a42c87d3",
            "cardUuid": "e81d2eb7-4fb8-42ed-be52-57057e2028b6",
            "requestUuid": "e2ed1ade-2f2d-463a-bc06-d49a1636cd76",
            "status": "ACTIVATED"
          }
          }
        
        


CARD_STATUS_CHANGE

Based on the use case cards that are in the activated state would need to be moved into a different statuses. Example: Fraud, or if the card is lost, etc. After the card’s status is successfully changed then the webhook response is posted on the designated url used while adding this webhook through SimpliFi Portal.

Below is the sample webhook response for the same.



Webhook Response
        
          {
            "eventType": "CARD_STATUS_CHANGE"
            "eventPayload": {
            "userUuid": "c8413ce7-ee59-490e-a5a3-a5aaa5dc3cbf",
            "reason": "RESTRICTED",
            "cardUuid": "10cffeb6-c533-4c85-a0be-3ce7bc601a59",
            "requestUuid": "7f85d010-7b77-4308-aa46-06c8ae104a34",
            "status": "LOCKED"
          }
          }
        
        


CARD_LOAD

Cards that are in the activated state could be loaded with funds to start making transactions. After the card’s load event is successful then the webhook response is posted on the designated url used while adding this webhook through SimpliFi Portal.

Below is the sample webhook response for the same.



Webhook Response
        
          {
            "eventType": "CARD_LOAD",
            "eventPayload": {
            "userUuid": "7163862a-e930-4302-aee2-8725d4288e7d",
            "cardUuid": "8485dff1-ecae-471f-9870-4960d1c72bdc",
            "loadStatus": "SUCCESSFUL",
            "cardProgramName": "Company TestPay",
            "requestUuid": "92e409f5-0d26-4d12-b56c-a69891c16573"
          }
          }
        
        


CARD_UNLOAD

Cards that are in the activated state and having funds in the card could be unloaded. After the card’s unload event is successful then the webhook response is posted on the designated url used while adding this webhook through SimpliFi Portal.

Below is the sample webhook response for the same.



Webhook Response
        
          {
            "eventType": "CARD_UNLOAD",
            "eventPayload": {
            "unloadStatus": "SUCCESSFUL",
            "userUuid": "7163862a-e930-4302-aee2-8725d4288e7d",
            "cardUuid": "8485dff1-ecae-471f-9870-4960d1c72bdc",
            "cardProgramName": "NECP QisstPay",
            "requestUuid": "32b01391-253e-4604-bd5b-c74ef2adb9ba"
          }
          }
        
        


CARD TYPE CHANGE

Cards that are virtual can be converted to physical. After the card type change event is successful then the webhook response is posted on the designated url used while adding this webhook through SimpliFi Portal.

Below is the sample webhook response for the same.



Webhook Response
        
          {
            "eventType": "CARD_TYPE_CHANGE",
            "eventPayload": {
            "cardType": "PHYSICAL",
            "userUuid": "2610d3eb-0a78-47ad-b9fd-a469ebc229da",
            "cardUuid": "543858f8-8b8c-42c7-a2f7-cc9ba6260a18",
            "maskedPan": "************8064",
            "cardStatus": "ISSUED"
          }
          }
        
        


CARD_HOLDER_CREATION

A card holder is created under a card program. A webhook is published whenever the “Create a User” event occurs and a user (Card Holder) is created using the SimpliFi platform.

Below is the sample webhook response for the same.



Webhook Response
        
          {
            "eventType": "CARD_HOLDER_CREATION",
            "eventPayload": {
            "userUuid": "1466d51e-0a88-4cca-99d8-c384919acfd2",
            "phoneNumber": "+971585441099",
            "userName": "Testuser",
            "email": "vollara@ramarailfans.ga",
            "requestUuid": "9f590d04-0891-4b06-961e-588cb0b5cc88"
          }
          }
        
        


CARD_HOLDER_UPDATION

A card holder record could be updated in the SimpliFi system. a webhook is published whenever the “Update a User” event occurs and the said user (Card Holder) is updated.

Below is the sample webhook response for the same.



Webhook Response
        
          {
            "eventType": "CARD_HOLDER_UPDATION",
            "eventPayload": {
            "userUuid": "1466d51e-0a88-4cca-99d8-c384919acfd2",
            "phoneNumber": "+971585441099",
            "userName": "Testuser",
            "email": "vollara@ramarailfans.ga",
            "requestUuid": "a8b63e34-1643-460d-b694-d3c3fa93b348"
          }
          }
        
        


CARD_HOLDER_DELETION

A card holder record could be deleted in the SimpliFi system. a webhook is published whenever the “Delete a User” event occurs and the said user (Card Holder) is updated.

Below is the sample webhook response for the same.



Webhook Response
        
          {
            "eventType": "CARD_HOLDER_DELETION",
            "eventPayload": {
            "userUuid": "c8413ce7-ee59-490e-a5a3-a5aaa5dc3cbf",
            "phoneNumber": "+97333888371",
            "userName": "Karen",
            "email": "andriyanovnikit@burgas.vip",
            "requestUuid": "98fa2051-028c-4b55-98c0-4e6f6ca8d0c5"
          }
          }
        
        


CARD_PROGRAM_CREATION

A card program is created in the SimpliFi system and a webhook is published.

Below is the sample webhook response for the same.



Webhook Response
        
          {
            "eventType": "CARD_PROGRAM_CREATION",
            "eventPayload": {
            "cardProgramUuid": "bd1adcce-d5ab-4592-8cad-f0178bf32246",
            "currency": "AED",
            "companyUuid": "c4f04bb4-292d-4030-931f-2e980900c29b",
            "cardProgramName": "Test Expense Card Program",
            "requestUuid": "ff8c0c3c-4255-4bb0-b317-f17cc56c2a29"
          }
          }
        
        


CARD_PROGRAM_UPDATION

When a card program is updated in the SimpliFi system and a webhook is published.

Below is the sample webhook response for the same.



Webhook Response
        
          {
            "eventType": "CARD_PROGRAM_UPDATION",
            "eventPayload": {
            "cardProgramUuid": "bd1adcce-d5ab-4592-8cad-f0178bf32246",
            "currency": "AED",
            "companyUuid": "c4f04bb4-292d-4030-931f-2e980900c29b",
            "cardProgramName": "Test Expense Card Program",
            "requestUuid": "3cf7f7f1-bc00-420a-ae0d-7389eebf5310"
          }
          }
        
        


RAISE_FUNDING_SOURCE

When funds are loaded/unloaded into a card program in the SimpliFi system and a webhook is published.

Below is the sample webhook response for the same.



Webhook Response
                    
                      {
                        "eventType": "RAISE_FUNDING_SOURCE",
                        "eventPayload": {
                        "transactionType": "CREDIT",
                        "cardProgramUuid": "2c839308-3c72-4c29-b8f2-d1d274b94217",
                        "amount": "500",
                        "companyUuid": "fcc84fd3-7289-4389-a64b-b3e033dc15f2",
                        "fundingSourceUuid": "ebef566e-4a1a-4cd4-9539-78f6f3b3940e"
                      }
                      }
                    
                

Enumerations

The APIs of the SimpliFi platform employ enumerations where a known set of responses is expected. The enumerations deployed within the SimpliFi platform are of “String” data type and this section elaborates each enumeration along with its expected values and their description.



1.1. Client_ID:

This enumeration appears while requesting an access token using the Login API in the SimpliFi platform. It represents the identity of the client by defining the OS platform of the client. Given below are the allowed values of this enumeration along with their description. It is recommended to have this enumeration while using the Login API to support any operation or to debug specific scenarios effectively.


Sr. No. Value Description
1 simplifi-ios-client This value represents that the client is accessing the system through an iOS device. Example: If you want to generate the access token to call subsequent APIs from your iOS mobile application then pass this value in Client_ID
2 simplifi-android-client This value represents that the client is accessing the system through an Android device. Example: If you want to generate the access token to call subsequent APIs from your Android mobile application then pass this value in Client_ID
3 simplifi-web-client This value represents that the client is accessing the system through a website. Example: If you want to generate the access token to call subsequent APIs from your iOS mobile application then pass this value in Client_ID
4 simplifi-api-client This value represents that the client is accessing the system directly on the API level. Example: Example: If you want to generate the access token to call subsequent APIs from your iOS mobile application then pass this value in Client_ID


1.2. CardProgramStatus:

This enumeration appears in response to such requests that represent the status of a Card Program at a given point.


Sr. No. Value Description
1 CREATED This value represents that the desired record has been created. This state appears when a card program is created but a funding source is not yet attached to it. This is the default status assigned when a Card Program is created.
2 simplifi-web-client Once a funding source is attached to the Card Program, its status is changed from “Created” to “Active”. This value represents that the desired record is in an active state. A card can only be issued for a card program in this state.
3 SUSPENDED This value represents that the desired record is in a suspended state. A suspended card program can be moved back to ACTIVE state.


1.3. Currency:

This enumeration appears when a currency is being requested or returned in a response. Given below are the allowed values of this enumeration along with their description.


Sr. No. Value Description
1 AED This value represents Arab Emirates Dirham as the currency.
2 USD This value represents United States Dollars as the currency.
3 PKR This value represents Pakistani Rupees as the currency.
4 SAR This value represents Saudi Riyal as the currency.
5 BHD This value represents Bahraini Dinar as the currency.
6 KWD This value represents Kuwaiti Dinar as the currency.
7 OMR This value represents Omani Riyal as the currency.
8 JOD This value represents Jordanian dinar as the currency.


1.4. Scheme (Deprecated):

This enumeration contains the card scheme of a card program template. Given below are the allowed values of this enumeration along with their description


Sr. No. Value Description
1 MASTER This value represents “Mastercard” as the card publisher.
2 VISA This value represents “Visa” as the card publisher.


1.5. Gender:

This enumeration contains the genders of users. Given below are the allowed values of this enumeration along with their description


Sr. No. Value Description
1 MALE This value represents the male gender for a user.
2 FEMALE This value represents the female gender for a user.


1.6. Instrument:

This enumeration specifies whether the card is a physical one or a virtual one. Given below are the allowed values of this enumeration along with their description.


Sr. No. Value Description
1 VIRTUAL This value represents a virtual card that can be electronically used.
2 PHYSICAL This value represents a physical card.


1.7. CardStatus:

This enumeration specifies the current status of a specific card. Given below are the allowed values of this enumeration along with their description.


Sr. No. Value Description
1 PENDING This value represents that the card is in pending state and cannot be used.
2 ISSUED This value represents that the card has been issued. An issued card cannot be used for any transactions unless it is in the ACTIVATED state.
3 ACTIVATED This value represents that the card is activated and can be used. A transaction can only happen for a card in this state.
4 DISABLED This value represents that the card cannot be used permanently.
5 LOCKED This value represents that the card is disabled temporarily and should be activated before using. An ideal use case for this state can be a state where a cardholder has reported card theft and no transaction through the card is desirable before it is found.
6 REPLACED This value represents that the card is replaced with another card. This usually happens if a cardholder has disabled a card and the client admin issues a replacement for that card.
7 REJECTED In case of any error while issuing a card (ex: unknown error), status would be assigned to “REJECTED”. Cards in this status cannot be activated.


1.8. UserStatus:

This enumeration specifies the current status of the user (card holder), as per its use. Given below are the allowed values of this enumeration along with their description.


Sr. No. Value Description
1 ACTIVE This value represents that the user record is successfully created in SimpliFi platform and is in ACTIVE status. A card can be issued to this user.
2 INACTIVE This value represents that the user has been permanently removed from the system.


1.9. Reason:

This enumeration specifies the reason for changing the card status. Given below are the allowed values of this enumeration along with their description.


Sr. No. Value Description
1 STOLEN If the card is stolen, pass this value in the Reason field
2 LOST If the card is lost, pass this value in the Reason field
3 FRAUDULENCE If there was any fraudulent activity on the card, pass this value in the Reason field
4 SECURITY_VIOLATION If the security of the card is compromised, pass this value in the Reason field
5 RESTRICTED If the card’s usage has to be restricted, pass this value in the Reason field


1.10. TransactionType:

This enumeration specifies the type of a transaction. Given below are the allowed values of this enumeration along with their description.


Sr. No. Value Description
1 AUTH This value represents that the transaction was authorized.
2 REVERSAL This value represents that the transaction was reversed.
3 SETTLEMENT This value represents that the AUTH transaction was settled.
4 REFUND This value represents that the transaction was refunded.


1.11. SourceFunds:

This enumeration specifies the source of funds. Given below are the allowed values of this enumeration along with their description.


Sr. No. Value Description
1 OTHER Default value to be passed


1.12. Purpose:

This enumeration specifies the purpose of the fund raising. Given below are the allowed values of this enumeration along with their description.


Sr. No. Value Description
1 OTHER Default value to be passed


1.13. DocumentType:

This enumeration specifies the document types allowed to be uploaded to the SimpliFi platform. Given below are the allowed values of this enumeration along with their description.


Sr. No. Value Description
1 ID_CARD This value represents that the document to be uploaded is a government issued ID Card.
2 PASSPORT This value represents that the document to be uploaded is a Passport.


1.14. DocumentContext:

This enumeration specifies the context of the document to be uploaded to the SimpliFi platform. Given below are the allowed values of this enumeration along with their description.


Sr. No. Value Description
1 DOCUMENT-FRONT This value represents that the front-side orientation of the ID card is being attached.
2 DOCUMENT-BACK This value represents that the back-side orientation of the ID card is being attached.
3 FACE This value represents that the face (front-side) of the document is being attached.


1.15. Transaction Status details:


Transaction Status Code Transaction Status Description Transaction Status
0 Approved Approve
5 Do not honor Decline
10 Partial Approval Approve
12 Invalid transaction Decline
13 Invalid amount Decline
14 Invalid card number Decline
51 Insufficient funds Decline
54 Expired card Decline
55 Invalid PIN Decline
57 Transaction not permitted to cardholder Decline
70 Contact Card Issuer Decline
85 Approved - Zero amount transactions Approve
62 Restricted Card Decline
65 Exceeds withdrawal count limit Decline
1 Auth Approved Approve
93 Auth Reversed by Scheme (Original Auth) Decline
97 Auth Reversal by Scheme (Reversed Auth) Decline
20 Auth Reversed by Issuer (Original Auth) Decline
95 Auth Reversal by Issuer (Reversed Auth) Decline
99 Txn Declined Decline

iOS SDK Integration Guide (v2.4.0)


Overview:

As the first step to integrating with the iOS SDK we recommend adding the dependencies using CocoaPods as this is mandatory. The dependencies are related to network logs within the SDK. This would help us debug issues for any requests made by the SDK.



How to install CocoaPods in your project:

1. If this is your first time using CocoaPods, Install CocoaPods using gem install cocoapods. Else start with Step 2

2. Create a Podfile in your Xcode project directory by running pod init in your terminal, edit the Podfile generated, and add the following line: pod 'Firebase/AnalyticsWithoutAdIdSupport'

3. Run pod install in your Xcode project directory. CocoaPods should download and install the Google analytics library, and create a new Xcode workspace. Open up this workspace in Xcode or typing open *.xcworkspace in your terminal

4. Refer the following link to learn more about How to use Cocoapods



How to integrate SimpliFi.framework in your project:

5. Import the SimpliFi.framework file (shared separately through google drive) into your respective project

6. After adding SimpliFi.framework in the project, go to project setting -> General as shown in the Figure below


7. Go to Embed and select the “Embed & Sign” option as shown in the Figure#1 above

8. Go to the controller where you want to implement the SimpliFi SDK functionality

9. Add Import SimpliFi as shown in line 10 of code in Figure #2

10. Please refer the SDK Methods section below to understand how to call the available methods





SDK Methods:



1. Display Card Details

This method will display the SDK’s UI to display user’s card details, including full pan, CVV and card expiry.



Method Name: displayCardDetails()


Parameters:

vc: UIViewController The UIViewController
token: String The JWT of the user which was received when user logged in
cardUdId: String The UUID of the card against which the information needs to be fetched
userIdentifier: String The UUID of the card holder
uri: String The base URL provided by simpliFi.

Example:


Simplifi.shared.displayCardDetails(token, cardUuid, userIdentifier,uri, vc)

2. Customization of Card Design:

This method must be called before displayCardDetails(). This method receives a Theme object where you can set various customization options.


Method Name: setTheme()


Parameters:

theme: ThemeOptions The theme to be used to update SDK’s look and feel

Example:

        
            Simplifi.shared.setTheme(
                ThemeOptions()
                    .setHeaderFont(font: .sanFrancisco)
                    .setBodyFont(font: .sanFrancisco)
                    .setButtonBackgroundColor(color: "#326ED7")
                    .setButtonTextColor(color: "#FFFFFF")
                    .setScreenBackgroundColor(color: "#FFFFFF")
                    .setTextColorOnCard(color: "#FFFFFF")
                    .build()
            )
        
        


ThemeOptions Methods:

setHeaderFont() Sets the font of the headings throughout the UIs presented by Simplifi SDK.
Pass the value of enum having all supported fonts.Default value: Montserrat
setBodyFont() Sets the font of the body text throughout the UIs presented by Simplifi SDK.
Pass the value of enum having all supported fonts. Default value: Montserrat
setButtonBackgroundColor() Sets the background color of buttons
Default value: #326ED7
setButtonTextColor() Sets the color of text displayed on buttons
Default value: #FFFFFF
setScreenBackgroundColor() Sets the color of screen’s background
Default value: #FFFFFF
setTextColorOnCard() Sets the color text displayed over the card image.
Default value: #FFFFFF

3. Enable Logs:

SimpliFi iOS SDK pushes only the non-sensitive information to GoogleAnalytics to track the issues quicker. Logging is enabled by default.


Method Name: enableLogs()


Parameters:

No parameters required

Example:


SimpliFi.shared.enableLogs()

4. Disable Logs:

SimpliFi iOS SDK pushes only the non-sensitive information to GoogleAnalytics to track the issues quicker. Logs are enabled by default. If you wish not to log any info, use this method to disable logging.


Method Name: disableLogs()


Parameters:

No parameters required

Example:


SimpliFi.shared.disableLogs()

NOTE: To enable physical card functionality you would need to have valid contracts with SimpliFi to start issuing Physical cards. If the physical card related methods are enabled without proper contracts in place they would break the SDK functionality

5. Request a Physical card:

This method will display the SDK Screen to request a physical card for a specific virtual card.


Method Name: requestPhysicalCard()


Parameters:

vc: UIViewController The UIViewController
token: String The JWT (JSON web token) of the cardholder which was received when the cardholder logs in using the SimpliFi Login API.
cardUuid: String The UUID of the virtual card for which physical card is to be requested
userIdentifier: String TThe UUID of the card holder
uri: String The base URL provided by SimpliFi (Depends on the environment)
Example: for UAT https://uat-lb.simplifipay.com/

Example:


SimpliFi.shared.requestPhysicalCard(token, cardUuid, userIdentifier, uri, vc)

6. Activate Physical card:

This method will display the SDK Screens to activate a physical card.


Method Name: activatePhysicalCard()


Parameters:

vc: UIViewController The UIViewController
token: String The JWT (JSON web token) of the cardholder which was received when the cardholder logs in using the SimpliFi Login API.
cardUuid: String The UUID of the virtual card for which physical card is to be requested
userIdentifier: String TThe UUID of the card holder
uri: String The base URL provided by SimpliFi (Depends on the environment)
Example: for UAT https://uat-lb.simplifipay.com/

Example:


SimpliFi.shared.activatePhysicalCard(token, cardUuid, userIdentifier, uri, vc)

7. Set Physical card PIN

This method will display the SDK Screens to set a PIN on a physical card.


Method Name: setPhysicalCardPin()


Parameters:

vc: UIViewController The UIViewController
token: String The JWT (JSON web token) of the cardholder which was received when the cardholder logs in using the SimpliFi Login API.
cardUuid: String The UUID of the virtual card for which physical card is to be requested
userIdentifier: String TThe UUID of the card holder
uri: String The base URL provided by SimpliFi (Depends on the environment)
Example: for UAT https://uat-lb.simplifipay.com/

Example:


SimpliFi.shared.setPhysicalCardPin(token, cardUuid, userIdentifier, uri, vc)

8. Get Physical card PIN

This method will display the SDK Screen to get a PIN on a physical card.


Method Name: getPhysicalCardPin()


Parameters:

vc: UIViewController The UIViewController
token: String The JWT (JSON web token) of the cardholder which was received when the cardholder logs in using the SimpliFi Login API.
cardUuid: String The UUID of the virtual card for which physical card is to be requested
userIdentifier: String TThe UUID of the card holder
uri: String The base URL provided by SimpliFi (Depends on the environment)
Example: for UAT https://uat-lb.simplifipay.com/

Example:


SimpliFi.shared.getPhysicalCardPin(token, cardUuid, userIdentifier, uri, vc)

Android SDK Integration Guide (v2.4.0)

Please follow these steps for integrating SimpliFi SDK with Android


1. Download the android library file (.aar) from the given path.

2. Place “.aar” file in “libs” folder located at following path,Android -> App -> Libs

3. Add following lines of code in app level build.gradle file in “dependencies” section,



                
                implementation fileTree(dir: 'libs', include: ['*.aar'])
                implementation 'com.squareup.okhttp3:okhttp:4.5.0'
                implementation 'com.google.code.gson:gson:2.8.6'
                implementation 'com.auth0.android:jwtdecode:2.0.0'
                
            

4. Add Following lines of code in project level build.gradle file in “dependencies” section under “buildscript”




classpath 'com.android.tools.build:gradle:7.0.3'

5. Add following lines of code in “gradle-wrapper.properties” file,


distributionUrl=https\://services.gradle.org/distributions/gradle-7.0.2-all.zip

6. Sync project with gradle files.


SDK Methods:



1. Initialize SDK



Method Name:

initialize()



Parameters:

uri: Context The base URL provided by simpliFi. It’s the URL on which SDK will execute its functions. The URL must end with a ‘/’

Example:


Simplifi.initialize(Uri)



2. Display Card Details

This method will display the SDK’s UI to display user’s card details, including full pan, CVV and card expiry.



Method Name:

displayCardDetails()



Parameters:

context: Context The activity context calling this method
USER_JWT: String The JWT of the user which was received when user logged in
CARD_UUID: String The UUID of the card against which the information needs to be fetched
User_Identifier: String The UUID of the card holder

Example:


Simplifi.displayCardDetails(context, USER_JWT, CARD_UUID, User_Identifier)

3. Customization of Card Design

This method >must be called before displayCardDetails() and after initialize(). This method receives a Theme object where you can set various customization options.



Method Name:

setTheme()



Parameters:

theme: ThemeOptions The theme to be used to update SDK’s look and feel

Example:

                
                    Simplifi.setTheme(
                    ThemeOptions.Builder()
                       .setHeaderFont(FontFace.F29LTBukra)
                       .setBodyFont(FontFace.Roboto)
                       .setButtonBackgroundColor("#326ED7")
                       .setButtonTextColor("#FFFFFF")
                       .setScreenBackgroundColor("#FFFFFF")
                       .setTextColorOnCard("#FFFFFF")
                       .build()
                    )
                
            

ThemeOptions Class:

ThemeOptions class would be instantiated through a builder. Create a builder instance, set all desired options and call the build method.



ThemeOptions.Builder Methods:

setHeaderFont() Sets the font of the headings throughout the UIs presented by Simplifi SDK.
Pass the value of enum having all supported fonts. Default value: Montserrat
setBodyFont() Sets the font of the body text throughout the UIs presented by Simplifi SDK.
Pass the value of enum having all supported fonts. Default value: Montserrat
setButtonBackgroundColor() Sets the background color of buttons
Default value: #326ED7
setButtonTextColor() Sets the color of text displayed on buttons
Default value: #326ED7
setScreenBackgroundColor() Sets the color of screen’s background
Default value: #FFFFFF
setTextColorOnCard() Sets the color text displayed over the card image.
Default value: #FFFFFF

4. Enable Logs:

SimpliFi Android SDK pushes only the non-sensitive information to GoogleAnalytics to track the issues quicker. Logging is enabled by default.


Method Name: enableLogs()


Parameters:

No parameters required

Example:


Simplifi.enableLogs()

5. Disable Logs:

SimpliFi Android SDK pushes only the non-sensitive information to GoogleAnalytics to track the issues quicker. Logs are enabled by default. If you wish not to log any info, use this method to disable logging.


Method Name: disableLogs()


Parameters:

No parameters required

Example:


Simplifi.disableLogs()

NOTE: To enable physical card functionality you would need to have valid contracts with SimpliFi to start issuing Physical cards. If the physical card related methods are enabled without proper contracts in place they would break the SDK functionality

6. Request a Physical card:

This method will display the SDK Screen to request a physical card for a specific virtual card.


Method Name: requestPhysicalCard()


Parameters:

context: Context The activity context calling this method
USER_JWT: String The JWT (JSON web token) of the cardholder which was received when the cardholder logs in using the SimpliFi Login API.
CARD_UUID: String The UUID of the virtual card for which physical card is to be requested
User_Identifier: String The UUID of the card holder

Example:


Simplifi.requestPhysicalCard(context, USER_JWT, CARD_UUID, User_Identifier)

7. Activate Physical card:

This method will display the SDK’s UI to activate a physical card.


Method Name: activatePhysicalCard()


Parameters:

context: Context The activity context calling this method
USER_JWT: String The JWT (JSON web token) of the cardholder which was received when the cardholder logs in using the SimpliFi Login API.
CARD_UUID: String The UUID of the virtual card for which physical card is to be requested
User_Identifier: String The UUID of the card holder

Example:


Simplifi.activatePhysicalCard(context, USER_JWT, CARD_UUID, User_Identifier)

8. Set Physical card PIN:

This method will display the SDK’s UI to set a PIN on a physical card.


Method Name: setPhysicalCardPin()


Parameters:

context: Context The activity context calling this method
USER_JWT: String The JWT (JSON web token) of the cardholder which was received when the cardholder logs in using the SimpliFi Login API.
CARD_UUID: String The UUID of the virtual card for which physical card is to be requested
User_Identifier: String The UUID of the card holder

Example:


Simplifi.setPhysicalCardPin(context, USER_JWT, CARD_UUID, User_Identifier)

9. Get Physical card PIN:

This method will display the SDK’s UI to retrieve a PIN that was last set on a physical card.


Method Name: setPhysicalCardPin()


Parameters:

context: Context The activity context calling this method
USER_JWT: String The JWT (JSON web token) of the cardholder which was received when the cardholder logs in using the SimpliFi Login API.
CARD_UUID: String The UUID of the virtual card for which physical card is to be requested
User_Identifier: String The UUID of the card holder

Example:


Simplifi.getPhysicalCardPin(context, USER_JWT, CARD_UUID, User_Identifier)
© 2021 SimpliFi