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.
This chapter includes general information related to the documentation in SimpliFi.
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. |
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. |
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.
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.
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. |
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.
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.
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:
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.
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.
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:
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).
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, 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.
We use standard HTTP response codes for anything we write.
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" |
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 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:
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 Company 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 Company. A user can not be a stand alone object without a relationship with a Company.
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.
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 company.
We also provide the ability to support the ledger maintenance at the company 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 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
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.
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.
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.
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.
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:
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.
{
"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 |
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.
USER_INVITE
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.
{
"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"
}
}
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.
{
"eventType": "CARD_ACTIVATION",
"eventPayload": {
"userUuid": "60978921-7000-4f2e-884c-0423a42c87d3",
"cardUuid": "e81d2eb7-4fb8-42ed-be52-57057e2028b6",
"requestUuid": "e2ed1ade-2f2d-463a-bc06-d49a1636cd76",
"status": "ACTIVATED"
}
}
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.
{
"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"
}
}
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.
{
"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"
}
}
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.
{
"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"
}
}
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.
{
"eventType": "CARD_TYPE_CHANGE",
"eventPayload": {
"cardType": "PHYSICAL",
"userUuid": "2610d3eb-0a78-47ad-b9fd-a469ebc229da",
"cardUuid": "543858f8-8b8c-42c7-a2f7-cc9ba6260a18",
"maskedPan": "************8064",
"cardStatus": "ISSUED"
}
}
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.
{
"eventType": "CARD_HOLDER_CREATION",
"eventPayload": {
"userUuid": "1466d51e-0a88-4cca-99d8-c384919acfd2",
"phoneNumber": "+971585441099",
"userName": "Testuser",
"email": "testuser@simplifipay.com",
"requestUuid": "9f590d04-0891-4b06-961e-588cb0b5cc88"
}
}
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.
{
"eventType": "CARD_HOLDER_UPDATION",
"eventPayload": {
"userUuid": "1466d51e-0a88-4cca-99d8-c384919acfd2",
"phoneNumber": "+971585441099",
"userName": "Testuser",
"email": "testuser@simplifipay.com",
"requestUuid": "a8b63e34-1643-460d-b694-d3c3fa93b348"
}
}
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.
{
"eventType": "CARD_HOLDER_DELETION",
"eventPayload": {
"userUuid": "c8413ce7-ee59-490e-a5a3-a5aaa5dc3cbf",
"phoneNumber": "+97333888371",
"userName": "Karen",
"email": "karen@simplifipay.com",
"requestUuid": "98fa2051-028c-4b55-98c0-4e6f6ca8d0c5"
}
}
A card program is created in the SimpliFi system and a webhook is published.
Below is the sample webhook response for the same.
{
"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"
}
}
When a card program is updated in the SimpliFi system and a webhook is published.
Below is the sample webhook response for the same.
{
"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"
}
}
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.
{
"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"
}
}
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.
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 |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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 |
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. |
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 |
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 |
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. |
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. |
| 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 |
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.
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
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
This method will display the SDK’s UI to display user’s card details, including full pan, CVV and card expiry.
| 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. |
Simplifi.shared.displayCardDetails(token, cardUuid, userIdentifier,uri, vc)
This method must be called before displayCardDetails(). This method receives a Theme object where you can set various customization options.
| theme: ThemeOptions | The theme to be used to update SDK’s look and feel |
Simplifi.shared.setTheme(ThemeOptions()
.setHeaderFont(font: .sanFrancisco)
.setBodyFont(font: .sanFrancisco)
.setButtonBackgroundColor(color: "#326ED7")
.setButtonTextColor(color: "#FFFFFF")
.setScreenBackgroundColor(color: "#FFFFFF")
.setTextColorOnCard(color: "#FFFFFF")
.build()
)
| 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 |
SimpliFi iOS SDK pushes only the non-sensitive information to GoogleAnalytics to track the issues quicker. Logging is enabled by default.
| No parameters required |
SimpliFi.shared.enableLogs()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.
| No parameters required |
SimpliFi.shared.disableLogs()This method will display the SDK Screen to request a physical card for a specific virtual card.
| 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/ |
SimpliFi.shared.requestPhysicalCard(token, cardUuid, userIdentifier, uri, vc)
This method will display the SDK Screens to activate a physical card.
| 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/ |
SimpliFi.shared.activatePhysicalCard(token, cardUuid, userIdentifier, uri, vc)
This method will display the SDK Screens to set a PIN on a physical card.
| 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/ |
SimpliFi.shared.setPhysicalCardPin(token, cardUuid, userIdentifier, uri, vc)
This method will display the SDK Screen to get a PIN on a physical card.
| 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/ |
SimpliFi.shared.getPhysicalCardPin(token, cardUuid, userIdentifier, uri, vc)
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.zip6. Sync project with gradle files.
initialize()
| 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 ‘/’ |
Simplifi.initialize(Uri)This method will display the SDK’s UI to display user’s card details, including full pan, CVV and card expiry.
displayCardDetails()
| 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 |
Simplifi.displayCardDetails(context, USER_JWT, CARD_UUID, User_Identifier)This method >must be called before displayCardDetails() and after initialize(). This method receives a Theme object where you can set various customization options.
setTheme()
| theme: ThemeOptions | The theme to be used to update SDK’s look and feel |
Simplifi.setTheme(ThemeOptions.Builder()
.setHeaderFont(FontFace.F29LTBukra)
.setBodyFont(FontFace.Roboto)
.setButtonBackgroundColor("#326ED7")
.setButtonTextColor("#FFFFFF")
.setScreenBackgroundColor("#FFFFFF")
.setTextColorOnCard("#FFFFFF")
.build()
)ThemeOptions class would be instantiated through a builder. Create a builder instance, set all desired options and call the build method.
| 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 |
SimpliFi Android SDK pushes only the non-sensitive information to GoogleAnalytics to track the issues quicker. Logging is enabled by default.
| No parameters required |
Simplifi.enableLogs()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.
| No parameters required |
Simplifi.disableLogs()This method will display the SDK Screen to request a physical card for a specific virtual card.
| 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 |
Simplifi.requestPhysicalCard(context, USER_JWT, CARD_UUID, User_Identifier)This method will display the SDK’s UI to activate a physical card.
| 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 |
Simplifi.activatePhysicalCard(context, USER_JWT, CARD_UUID, User_Identifier)This method will display the SDK’s UI to set a PIN on a physical card.
| 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 |
Simplifi.setPhysicalCardPin(context, USER_JWT, CARD_UUID, User_Identifier)This method will display the SDK’s UI to retrieve a PIN that was last set on a physical card.
| 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 |
Simplifi.getPhysicalCardPin(context, USER_JWT, CARD_UUID, User_Identifier)