SimpliFi
Home Product Solutions Contact Us Go to Portal

OpenAPI definition (v1)

Cards

The ‘Cards’ API Group is designed to manage all the activities related to the cards life cycle. Cards can either be issued in physical or virtual form, or both. Cards would inherit the default characteristics of the card program under which they have been issued, however, some of these can be changed at the card level. Cards could be issued only to a registered user (card holder) within a card program.

Verify the OTP to Activate the Physical Card

path Parameters
uuid
required
string

This field contains the system-generated unique identifier of the “physical” card taken as a parameter in the request curl.

Request Body schema: application/json
otp
string

This is the OTP that is received on the card holder’s mobile number used while creating a card holder record.

Responses

Request samples

Content type
application/json
{
  • "otp": "32156"
}

Unload a Card

The ‘Unload a Card’ endpoint removes funds from an active card and moves them back to the Funding source (Virtual account that holds the funds in certain currency). Following are the properties of this endpoint.

path Parameters
uuid
required
string <uuid>

This is a system-generated unique identifier of the card that was created using the Create Card API.

header Parameters
requestUuid
required
string <uuid>

Request Uuid

Request Body schema: application/json
cardUuid
string <uuid>

(deprecated) This field contains a unique identifier of the card.

loadAmount
number

(deprecated) This field contains the amount that has been successfully loaded onto a card.

requestedAmount
number

This field contains the amount that has been requested to be loaded onto a card.

status
string
Enum: "PENDING" "APPROVED"

(deprecated) This field contains the status (PENDING, APPROVED) of the fund load request on the card.

userUuid
string <uuid>

(deprecated) This field contains a unique identifier of the card holder.

uuid
string <uuid>

(deprecated) This field contains a unique identifier of the card taken as a parameter in the request curl.

Responses

Request samples

Content type
application/json
{
  • "uuid": "11e082c2-993d-4026-82c4-1234ec464796",
  • "userUuid": "11e082c2-993d-4026-82c4-1234ec464796",
  • "cardUuid": "11e082c2-993d-4026-82c4-1234ec464796",
  • "requestedAmount": 100,
  • "loadAmount": 100,
  • "status": "PENDING"
}

Manage Card Status

The ‘Manage Card Status’ endpoint manages the status of a card. This endpoint is helpful as cards can be locked (temporarily suspended), disabled, reissued depending upon the business requirements. Following are the properties of this endpoint.

path Parameters
uuid
required
string <uuid>

This is a system-generated unique identifier of the card that was created using the Create Card API.

header Parameters
requestUuid
required
string <uuid>

Request Uuid

Request Body schema: application/json
details
string

This field contains any relevant details to be posted alongside the reason for changing the card status.

reason
string
Enum: "ALL_GOOD" "STOLEN" "LOST" "FRAUDULENCE" "SECURITY_VIOLATION" "RESTRICTED" "VOIDED"

This field specifies the reason for changing the card status.

status
string
Enum: "PENDING" "ISSUED" "PROVISIONED" "ACTIVATED" "DISABLED" "LOCKED" "REPLACED" "REJECTED"

Responses

Request samples

Content type
application/json
{
  • "status": "PENDING",
  • "reason": "stolen",
  • "details": "lost due to natural disaster"
}

Renewal of the Card

The ‘Renewal of the Card’ endpoint renews an expired, lost, or stolen card. In this case, a new Primary Account Number (PAN) would be issued from the prevalent settings of the relevant card program. Following are the properties of this endpoint.

path Parameters
uuid
required
string <uuid>

This is a system-generated unique identifier of the card that was created using the Create Card API.

header Parameters
requestUuid
required
string <uuid>

This field contains a unique identifier for the request and is passed as a header along with the request.

Responses

Response samples

Content type
application/json
{
  • "originalCardUuid": "2bb08d1e-d870-4759-af95-e1e897999e63",
  • "renewedCardUuid": "d076a792-7895-47ba-9e30-30bf43031efb"
}

Get PIN for Physical Card

The ‘Get PIN for Physical Card’ endpoint retrieves the Personal Identification Number (PIN) previously set for a physical card, against the Card UUID parameter. Note (this endpoint is specific to physical cards and cannot be used for virtual cards). Following are the properties of this endpoint.

path Parameters
uuid
required
string <uuid>

This field contains a system-generated unique identifier of the physical card taken as a parameter in the request curl.

Responses

Response samples

Content type
application/json
{
  • "pin": "123456"
}

Set PIN for Physical Card

The ‘Set PIN for Physical Card’ endpoint sets a Personal Identification Number (PIN) for the physical card that is in the activated state. Note (this endpoint is specific to physical cards and cannot be used for virtual cards). Following are the properties of this endpoint.

path Parameters
uuid
required
string

This is a system-generated unique identifier of the card that was created using the Create Card API.

Request Body schema: application/json
pin
string [ 4 .. 5 ] characters

This field contains the Personal Identification Number (PIN) to be set for a physical card by the card holder. (4 digit number)

Responses

Request samples

Content type
application/json
{
  • "pin": "12345"
}

Response samples

Content type
application/json
{
  • "otp": "32156"
}

Load a Card

The ‘Load a Card’ endpoint adds funds to an active card. Following are the properties of this endpoint.

path Parameters
uuid
required
string <uuid>

This is a system-generated unique identifier of the card that was created using the Create Card API.

header Parameters
requestUuid
required
string <uuid>

Request Uuid

Request Body schema: application/json
cardUuid
string <uuid>

(deprecated) This field contains a unique identifier of the card.

loadAmount
number

(deprecated) This field contains the amount that has been successfully loaded onto a card.

requestedAmount
number

This field contains the amount that has been requested to be loaded onto a card.

status
string
Enum: "PENDING" "APPROVED"

(deprecated) This field contains the status (PENDING, APPROVED) of the fund load request on the card.

userUuid
string <uuid>

(deprecated) This field contains a unique identifier of the card holder.

uuid
string <uuid>

(deprecated) This field contains a unique identifier of the card taken as a parameter in the request curl.

Responses

Request samples

Content type
application/json
{
  • "uuid": "11e082c2-993d-4026-82c4-1234ec464796",
  • "userUuid": "11e082c2-993d-4026-82c4-1234ec464796",
  • "cardUuid": "11e082c2-993d-4026-82c4-1234ec464796",
  • "requestedAmount": 100,
  • "loadAmount": 100,
  • "status": "PENDING"
}

Generate the OTP to Activate the Physical Card

path Parameters
uuid
required
string

This field contains the system-generated unique identifier of the “physical” card taken as a parameter in the request curl.

Responses

Response samples

Content type
application/json
{
  • "otp": "32156"
}

Regenerate OTP for Physical Card

path Parameters
uuid
required
string

This field contains the system-generated unique identifier of the “physical” card taken as a parameter in the request curl.

Responses

Response samples

Content type
application/json
{
  • "otp": "32156"
}

Verify the OTP for Physical Card Set Pin

path Parameters
uuid
required
string

This field contains the system-generated unique identifier of the “physical” card taken as a parameter in the request curl.

Request Body schema: application/json
otp
string

This is the OTP that is received on the card holder’s mobile number used while creating a card holder record.

Responses

Request samples

Content type
application/json
{
  • "otp": "32156"
}

Activate a Card

The ‘Activate a Card’ endpoint activates an issued/created card. Following are the properties of this endpoint.

path Parameters
uuid
required
string <uuid>

This is a system-generated unique identifier of the card that was created using the Create Card API.

Request Body schema: application/json
userUuid
string <uuid>

(deprecated) This field contains a unique identifier of the card holder.

Responses

Request samples

Content type
application/json
{
  • "userUuid": "11e082c2-993d-4026-82c4-1234ec464796"
}

Create a Card

The ‘Create a Card’ endpoint creates/issues a card to a card holder under a Card Program. The card issued using this endpoint would inherit the characteristics defined in its card program such as authorization controls, velocity controls etc. It is recommended to issue a card in an inactive (issued) state with zero balance as default. Following are the properties of this endpoint.

header Parameters
requestUuid
required
string <uuid>

Request Uuid

Request Body schema: application/json
cardProgramUuid
string <uuid>

This is a system-generated unique identifier for the card program that was created using the Create Card Program API.

customerTitle
string

This is a specific name for the card holder to be displayed on the card in addition to the cardholder name. This field adds another layer of individuality and exclusivity for the card holder. Also known as 4th line embossing.

instrument
string
Enum: "VIRTUAL" "PHYSICAL" "VIRTUAL_AND_PHYSICAL" "CLIENT_CARD"
userUuid
required
string <uuid>

This is a system-generated unique identifier of the card holder that was created using the Create User API.

Responses

Request samples

Content type
application/json
{
  • "userUuid": "11e082c2-993d-4026-82c4-1234ec464796",
  • "cardProgramUuid": "11e082c2-993d-4026-82c4-1234ec464796",
  • "customerTitle": "Team Member",
  • "instrument": "VIRTUAL"
}

Response samples

Content type
application/json
{
  • "uuid": "11e082c2-993d-4026-82c4-1234ec464796",
  • "userUuid": "11e082c2-993d-4026-82c4-1234ec464796",
  • "traceUuid": "11e082c2-993d-4026-82c4-1234ec464796",
  • "companyUuid": "11e082c2-993d-4026-82c4-1234ec464796",
  • "cardProgramUuid": "11e082c2-993d-4026-82c4-1234ec464796",
  • "instrument": "VIRTUAL",
  • "usageType": "REGULAR",
  • "pinEnabled": false,
  • "startDate": "yyyy-MM-dd hh:mm:ss",
  • "creationDate": "yyyy-MM-dd hh:mm:ss",
  • "lastModified": "yyyy-MM-dd hh:mm:ss",
  • "cardStatus": "PENDING",
  • "expiryDate": "expiryDate",
  • "maskedPan": "**********1234",
  • "cardMode": "PRIMARY"
}

Get card statement

Get card statement based on date range.

path Parameters
uuid
required
string

The unique ID of the card.

query Parameters
endDate
string

end date of date-range

startDate
string

start date of date-range

Responses

Response samples

Content type
application/json
{
  • "companyName": "SimpliFi",
  • "statementDate": "yyyy-MM-dd",
  • "maskPan": "************1234",
  • "currency": "SAR",
  • "startDate": "yyyy-MM-dd hh:mm:ss.nnn",
  • "endDate": "yyyy-MM-dd hh:mm:ss.nnn",
  • "openingBalance": 6.95,
  • "currentBalance": 6.95,
  • "settledBalance": 6.95,
  • "unsettledBalance": 6.95,
  • "totals": {
    },
  • "transactions": [ ]
}

Request a Physical Card

The ‘Request a Physical Card’ endpoint issues a Physical card against the Card UUID of the activated virtual card. Note (this endpoint is specific to physical cards and cannot be used for virtual cards. Physical cards should be issued only for a virtual card in “ACTIVE” status). Following are the properties of this endpoint.

path Parameters
uuid
required
string

This field contains a system-generated unique identifier of the “virtual” card taken as a parameter in the request curl. It is mandatory to have a virtual card first in ACTIVE status before issuing a Physical card.

Responses

Retrieve Balance on the Card

The ‘Retrieve Balance on the Card’ endpoint retrieves the remaining balance of a card. Following are the properties of this endpoint.

path Parameters
uuid
required
string <uuid>

This is a system-generated unique identifier of the card that was created using the Create Card API.

query Parameters
userUuid
string <uuid>

This is a system-generated unique identifier of the card holder that was created using the Create User API.

header Parameters
requestUuid
required
string <uuid>

This field contains a unique identifier for the request.

Responses

Response samples

Content type
application/json
{
  • "amount": 100,
  • "currency": "PKR"
}

Get Card Details

The ‘Get Card Details’ endpoint retrieves all the details of a specific card. Following are the properties of this endpoint.

path Parameters
uuid
required
string <uuid>

This is a system-generated unique identifier of the card that was created using the Create Card API.

Responses

Response samples

Content type
application/json
{
  • "uuid": "11e082c2-993d-4026-82c4-1234ec464796",
  • "userUuid": "11e082c2-993d-4026-82c4-1234ec464796",
  • "traceUuid": "11e082c2-993d-4026-82c4-1234ec464796",
  • "companyUuid": "11e082c2-993d-4026-82c4-1234ec464796",
  • "cardProgramUuid": "11e082c2-993d-4026-82c4-1234ec464796",
  • "instrument": "VIRTUAL",
  • "usageType": "REGULAR",
  • "pinEnabled": false,
  • "startDate": "yyyy-MM-dd hh:mm:ss",
  • "creationDate": "yyyy-MM-dd hh:mm:ss",
  • "lastModified": "yyyy-MM-dd hh:mm:ss",
  • "cardStatus": "PENDING",
  • "expiryDate": "expiryDate",
  • "maskedPan": "**********1234",
  • "cardMode": "PRIMARY"
}

Get Transactions Statement

The ‘Get Transaction Statement’ endpoint retrieves a statement of all the transactions against a card. The transaction statement can be filtered based on a date range. Following are the properties of this endpoint.

path Parameters
cardUuid
required
string

This field contains a unique identifier of the Card.

query Parameters
endDate
string <date>

This field contains the end date of the range to be provided for user search. Refer to the data types table for acceptable format of date.

startDate
string <date>

This field contains the start date of the range to be provided for user search. Refer to the data types table for acceptable format of date.

header Parameters
requestUuid
required
string

Request Uuid

Responses

Response samples

Content type
application/json
{
  • "startBalance": 100,
  • "endBalance": 200,
  • "currencyBill": "PKR",
  • "availableBalance": 100,
  • "blockedAmount": 50,
  • "transactions": [
    ]
}

Get Settlement by Card ID

The ‘Get Settlement by Card ID’ endpoint retrieves all the settled transactions of a card using the Card UUID parameter. Following are the properties of this endpoint.

path Parameters
cardUuid
required
string

This field contains a unique identifier of the card taken as a parameter in the request curl.

query Parameters
endDate
string <date>

This field contains the end date to be provided to filter the transaction records. Refer to the data types table for acceptable format of date.

page
string
Default: "1"

This field contains the page number currently being displayed for transactions. The default value for this field is “1”.

pageSize
string
Default: "10"

This field contains the size of the page that is displaying transactions. The default value for this field is “10”.

startDate
string <date>

This field contains the start date to be provided to filter the transaction records. Refer to the data types table for acceptable format of date.

Responses

Response samples

Content type
application/json
{
  • "tlementDate": { },
  • "transactionId": "123",
  • "settlementDate": "2021-10-22 11:30:30",
  • "account": "123-456",
  • "token": "45678",
  • "billingAmount": 45678,
  • "transactionDate": "2021-10-22 11:30:30",
  • "mcc": "ACCEPTED",
  • "description": "test",
  • "address": "test",
  • "city": "karachi",
  • "postalCode": "7650",
  • "state": "sindh",
  • "country": "pakistan",
  • "currency": "PKR",
  • "transactionType": "SETTLEMENT"
}

Get Authorization by Card ID

The ‘Get Authorization by Card ID’ retrieves all the authorized transactions of a card using the Card UUID parameter. Following are the properties of this endpoint.

path Parameters
cardUuid
required
string

This is a system-generated unique identifier of the card that was created using the Create Card API.

query Parameters
endDate
string <date>

This field contains the end date to be provided to filter the transaction records. Refer to the data types table for acceptable format of date.

page
string
Default: "1"

This field contains the page number currently being displayed for transactions. The default value for this field is “1”.

pageSize
string
Default: "10"

This field contains the size of the page that is displaying transactions. The default value for this field is “10”.

startDate
string <date>

This field contains the start date to be provided to filter the transaction records. Refer to the data types table for acceptable format of date.

Responses

Response samples

Content type
application/json
{
  • "account": "123-456",
  • "token": "45678",
  • "amountBill": 20,
  • "transactionId": "123",
  • "mtId": "abcdefghij",
  • "transactionAmount": 300,
  • "status": "SUCCESS",
  • "description": "test",
  • "city": "ACCEPTED",
  • "state": "ACCEPTED",
  • "currency": "PKR",
  • "terminalId": "12",
  • "finalDebit": "123",
  • "transactionStatus": "APPROVED",
  • "transactionType": "AUTH",
  • "transactionDate": "2021-10-22 11:30:30",
  • "mcc": "ACCEPTED",
  • "currDecno": "USD"
}

Card Control

The ‘Card Control’ API Group is designed to assign controls over the card's usage. These controls include transaction limits (also known as the velocity controls) and other amenities such as using cards over ATM, POS and other E-Commerce gateways (Authorization controls). Cards created under a Card program will inherit the card controls of the card program. However, customized card controls can be created and managed to restrict card holder’s usage of the card. In a nutshell, there are two main functions of this API group, given as below:

  • Authorization Control: Configuring the Point of Interest (POI) where the card can be used.
  • Velocity Control: Setting limits on the amount of transactions and the frequency of usage.

Note: Velocity controls has two identifiers:

  1. Velocity control Key (This information would be shared separately) If you don't have it already, you can request it through this link.
  2. Velocity control Name - This is the custom name that could be assigned to the velocity control keys.

Get Card Control

The ‘Get Card Control’ endpoint retrieves details about a card control. The card control functionality is helpful in assigning controls over a card’s vital features such as POI and velocity controls etc. Following are the properties of this endpoint.

path Parameters
uuid
required
string

This is the unique identifier of the card.

query Parameters
cardProgramUuid
string

This is the unique identifier of the card program to which the card belongs.

Responses

Response samples

Content type
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "cardUuid": "e5020885-a6f5-48ee-8646-8210b0dd33cf",
  • "cardProgramUuid": "5aa89ef0-2678-4509-a330-672dc9dd3307",
  • "cardControl": {
    }
}

Update Card Control

The ‘Update Card Control’ endpoint updates the controls that were previously set on the card. The Card Control functionality is helpful in assigning controls over a card’s vital features such as POI (touch points where the card could be used) and velocity controls etc. Following are the properties of this endpoint.

path Parameters
uuid
required
string

This field contains the unique identifier of the cardholder.

Request Body schema: application/json
object

This object is a collection of configuration fields including both Point of Interest and Velocity Control fields. It contains sub-fields explained in the rows below.

cardProgramUuid
string <uuid>

This is a unique identifier for the program that was created using the Create Card Program API.

cardUuid
string <uuid>

This is the unique identifier of the card.

Responses

Request samples

Content type
application/json
{
  • "cardUuid": "e5020885-a6f5-48ee-8646-8210b0dd33cf",
  • "cardProgramUuid": "5aa89ef0-2678-4509-a330-672dc9dd3307",
  • "cardControl": {
    }
}

Response samples

Content type
application/json
{
  • "cardUuid": "e5020885-a6f5-48ee-8646-8210b0dd33cf",
  • "cardProgramUuid": "5aa89ef0-2678-4509-a330-672dc9dd3307",
  • "cardControl": {
    }
}

Create Card Control

The ‘Create Card Control’ endpoint assigns controls around where and how often a card can be used by the card holders. The Card control functionality is helpful in applying controls over a card’s vital features such as POI (touch points where the card could be used) and velocity controls etc. Following are the properties of this endpoint.

Request Body schema: application/json
object

This object is a collection of configuration fields including both Point of Interest and Velocity Control fields. It contains sub-fields explained in the rows below.

cardProgramUuid
string <uuid>

This is a unique identifier for the program that was created using the Create Card Program API.

cardUuid
string <uuid>

This is the unique identifier of the card.

Responses

Request samples

Content type
application/json
{
  • "cardUuid": "e5020885-a6f5-48ee-8646-8210b0dd33cf",
  • "cardProgramUuid": "5aa89ef0-2678-4509-a330-672dc9dd3307",
  • "cardControl": {
    }
}

Response samples

Content type
application/json
{
  • "cardUuid": "e5020885-a6f5-48ee-8646-8210b0dd33cf",
  • "cardProgramUuid": "5aa89ef0-2678-4509-a330-672dc9dd3307",
  • "cardControl": {
    }
}

Card Program

The ‘Card Program’ API Group is designed to manage common features among cards, by grouping them under a card program. The SimpliFi platform would create a bespoke card program template based on your requirements such as the scheme, validity of the cards, form factor of the cards, authorization controls, velocity controls etc. You would be able to create a card program using this template.

Every card issued under a card program inherits the characteristics of that card program. Card program templates are shared separately and if you don’t have them already, click on this link.

Get Card Program

The ‘Get Card Program’ endpoint retrieves details about a card program. Following are the properties of this endpoint.

path Parameters
uuid
required
string

This is a unique identifier for the program that was created using the Create Card Program API.

Responses

Response samples

Content type
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "name": "Example Card Product",
  • "kycRequired": true,
  • "parentAccountId": "string",
  • "productId": "string",
  • "fundingSourceUuid": "21aa4499-f0e5-4478-bcd6-bbb59ed784db",
  • "cardProgramStatus": "CREATED",
  • "config": {
    },
  • "cardProgramTemplateUuid": "41e60279-b79d-499f-8c06-0fccbce2d16f",
  • "cardProgramTemplateName": "Simplifi Card program Template",
  • "cardProgramTemplate": {
    },
  • "currency": "PKR"
}

Update Card Program

The 'Update Card Program' endpoint allows API users to update/overwrite the settings of a card program within the SimpliFi platform. Following are the properties of this endpoint.

path Parameters
uuid
required
string

CardProgram UUID

Request Body schema: application/json
cardProgramStatus
string
Enum: "CREATED" "ACTIVE" "INACTIVE" "SUSPENDED"

This field specifies the status (CREATED, ACTIVE, INACTIVE, SUSPENDED) of the card program.

cardProgramTemplateUuid
string

This is a unique identifier that represents a specific card program template. A Card Program Template contains all the features applicable on a card that would be issued under a card program. This information is shared by SimpliFi separately. If you don’t have them already, click on this link.

object

This object is a collection of configuration fields including both Point of Interest and Velocity Control fields. It contains sub-fields explained in the rows below.

kycRequired
boolean

(deprecated) This field specifies whether KYC is required for this card program or not.

name
string

This is a custom name for the card program. We recommend choosing a unique name to identify the card programs that are created under your company.

uuid
string <uuid>

This is a system-generated unique identifier for the card program that was created by this endpoint.

Responses

Request samples

Content type
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "name": "Example Card Product",
  • "kycRequired": true,
  • "cardProgramStatus": "CREATED",
  • "config": {
    },
  • "cardProgramTemplateUuid": "123-a-213"
}

Response samples

Content type
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "name": "Example Card Product",
  • "kycRequired": true,
  • "cardProgramStatus": "CREATED",
  • "config": {
    },
  • "cardProgramTemplateUuid": "123-a-213"
}

Create Card Program

The 'Create Card Program' endpoint allows API users to create a new card program to be associated with cards of the SimpliFi platform. Following are the properties of this endpoint.

Request Body schema: application/json
cardProgramStatus
string
Enum: "CREATED" "ACTIVE" "INACTIVE" "SUSPENDED"

This field specifies the status (CREATED, ACTIVE, INACTIVE, SUSPENDED) of the card program.

cardProgramTemplateUuid
string

This is a unique identifier that represents a specific card program template. A Card Program Template contains all the features applicable on a card that would be issued under a card program. This information is shared by SimpliFi separately. If you don’t have them already, click on this link.

object

This object is a collection of configuration fields including both Point of Interest and Velocity Control fields. It contains sub-fields explained in the rows below.

kycRequired
boolean

(deprecated) This field specifies whether KYC is required for this card program or not.

name
string

This is a custom name for the card program. We recommend choosing a unique name to identify the card programs that are created under your company.

uuid
string <uuid>

This is a system-generated unique identifier for the card program that was created by this endpoint.

Responses

Request samples

Content type
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "name": "Example Card Product",
  • "kycRequired": true,
  • "cardProgramStatus": "CREATED",
  • "config": {
    },
  • "cardProgramTemplateUuid": "123-a-213"
}

Response samples

Content type
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "name": "Example Card Product",
  • "kycRequired": true,
  • "cardProgramStatus": "CREATED",
  • "config": {
    },
  • "cardProgramTemplateUuid": "123-a-213"
}

Change Card Program Status

The ‘Change Card Program Status’ endpoint changes the status of a card program. This endpoint is helpful when a card program is to be suspended or activated as per the business needs. Following are the properties of this endpoint.

path Parameters
uuid
required
string

This is a unique identifier for the card program generated during the card program creation.

Request Body schema: application/json
cardProgramStatus
string
Enum: "ACTIVE" "SUSPENDED" "INACTIVE"

This field specifies the status (ACTIVE, SUSPENDED, INACTIVE) of the Card Program.

Responses

Request samples

Content type
application/json
{
  • "cardProgramStatus": "ACTIVE"
}

Document

The ‘Document’ API Group is designed to allow users to handle documents of the SimpliFi system which are simply referred to as ‘Documents’.

Raise Funding Document Upload

This API should be called before calling Raise Funding API to attach “Proof of funds / Confirmation of funds transfer from the Bank” document (PNG, JPEG,PDF are allowed formats) and the string value returned in the fileUrl field of the response should be used in Raise Funding API’s attachment parameter. Note: After the funds are transferred from the whitelisted Bank account to the Issuer/Processor Bank account, the confirmation of transfer of funds screenshot/image/PDF should be used as an attachment.

header Parameters
authorization
required
string

Authorization Token

requestUuid
required
string

Request Uuid

Request Body schema: multipart/form-data
file
required
string <binary>
object

Responses

Response samples

Content type
application/json
{
  • "fileUrl": "string",
  • "cardProgramUuid": "f242acc1-bcbf-11eb-8529-c070bc3a2325",
  • "amount": 100,
  • "fundRequestType": "LOAD"
}

Upload Document

The ‘Upload Document’ endpoint uploads the user documents to the SimpliFi system which are required as part of the sanctions screening or KYC process. The documents can be uploaded in one of the following formats (.JPG, .JPEG, .PNG)

header Parameters
authorization
required
string

Authorization Token

requestUuid
required
string

Request Uuid

Request Body schema: multipart/form-data
object
file
required
string <binary>

Responses

Response samples

Content type
application/json
{
  • "uuid": "f242acc1-bcbf-11eb-8529-c070bc3a2323",
  • "userUuid": "f242acc1-bcbf-11eb-8529-c070bc3a2323",
  • "documentType": "PASSPORT",
  • "documentContext": "DOCUMENT_FRONT"
}

Auth

The ‘Auth’ API Group is designed to authorize you to start using the SimpliFi platform. This group has the ‘Login’ endpoint that allows you to enter into our system. Moreover, the endpoint’s response provides you with the access token, which would be used in making further API calls.

Login

The ‘Login’ endpoint allows you to login to the SimpliFi platform using the provided credentials. If you don't have the credentials already, you can request them through this link. The endpoint returns an access token to be used in making further API calls. Following are the properties of this endpoint.

path Parameters
companyName
required
string

This is an internal identifier of your company in the SimpliFi platform. We will generate the company name for you and share it. If you don't have it already, you can request it through this link.

Request Body schema: application/x-www-form-urlencoded
client_id
required
string

The values of this enumeration identify your channel for calling the endpoint. Example: If you want to generate the access token to call subsequent APIs from your back-end system then use the value simplifi-api-client. Allowed values are: simplifi-ios-client, simplifi-android-client, simplifi-web-client, and simplifi-api-client.

client_secret
required
string

This is a secret identification pattern assigned to you by the SimpliFi platform. For each allowed value of “client_id” there is a respective client secret value shared with you before the start of the integration. Pass the respective value here. If you don't have it already, you can request it through this link.

grant_type
required
string

You need to pass this value to log in through the Client Secret shared by SimpliFi. Allowed value is client_credentials. If you don't already have these credentials, you can request them through this link.

Responses

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "expires_in": "string",
  • "refresh_expires_in": "string",
  • "refresh_token": "string",
  • "token_type": "string",
  • "not-before-policy": "string",
  • "session_state": "string",
  • "scope": "string"
}

Funding Source

The ‘Funding Source’ API Group is designed to add and manage the funding sources under a Company. Funding source is the equivalent of an unique account where all the funds related to this funding source are pooled. Each card program should be linked with a funding source so that funds from the funding source could be used to load cards issued under this Card program. A Funding source will have funds in one currency only and to hold funds in multiple currencies multiple funding sources would have to be created and assigned to a Company.

Funding source information would be shared with SimpliFi’s clients separately and if you don’t have them already, click on this link.

Update Funding Source

The ‘Update Funding Source’ endpoint replaces an existing funding source of a Card program with a new funding source. Following are the properties of this endpoint.

path Parameters
fundingSourceUuid
required
string

This field contains a unique identifier of the funding source linked to the card program.

uuid
required
string

This field contains the system generated unique identifier for the program that was created using the Create Card Program API.

Request Body schema: application/json
fundingSource
string

This field contains a token that identifies the funding source that is to be linked with the card program. This information will be shared separately.If you don’t have them already, click on this link.

thirdPartyId
string

(deprecated) This field contains a unique ID to identify the funding source as a valid third party. This field has been deprecated. Please use the fundingSource parameter to identify the funding source.

Responses

Request samples

Content type
application/json
{
  • "thirdPartyId": "123",
  • "fundingSource": "123"
}

Response samples

Content type
application/json
{
  • "uuid": "12z-126452",
  • "cardProgramUuid": "12z-126452",
  • "thirdPartyId": "123",
  • "fundingSource": "123",
  • "currency": "PKR"
}

Link Funding Source to Card Program

The ‘Link Funding Source to Card Program’ endpoint links a funding source to a card program. The funding source works as an account that would be used to fund all its cards under this Card Program. Following are the properties of this endpoint.

path Parameters
uuid
required
string

This is a system-generated unique identifier for the card program to which the funding source is to be linked.

Request Body schema: application/json
fundingSource
string

This field contains a token that identifies the funding source that is to be linked with the card program. This information will be shared separately.If you don’t have them already, click on this link.

thirdPartyId
string

(deprecated) This field contains a unique ID to identify the funding source as a valid third party. This field has been deprecated. Please use the fundingSource parameter to identify the funding source.

Responses

Request samples

Content type
application/json
{
  • "thirdPartyId": "123",
  • "fundingSource": "123"
}

Response samples

Content type
application/json
{
  • "uuid": "12z-126452",
  • "cardProgramUuid": "12z-126452",
  • "thirdPartyId": "123",
  • "fundingSource": "123",
  • "currency": "PKR"
}

Transfer funds from one Card Program to other

The 'transfer fund' endpoint allows API users to transfer funds from a one Card Program to other Card Program. Following are the properties of this endpoint.

Request Body schema: application/json
amount
number

Amount to be transferred.

destCardProgramUuid
string

Destination Card program UUID from where funds is being transferred.

sourceCardProgramUuid
string

Source Card program UUID from where funds is being transferred.

Responses

Request samples

Content type
application/json
{
  • "sourceCardProgramUuid": "abdhc-jsjkn-aksbkxbkk-sjdbj",
  • "destCardProgramUuid": "abdhc-jsjkn-aksbkxbkk-sjdbd",
  • "amount": 100
}

Raise Funding

The ‘Raise Funding’ endpoint helps in adding or removing funds from a funding source. This API doesn’t actually move the money between accounts but should be used so that the proof of funds is shared with the Issuer/Processor Bank. After the proof of funds attachment is verified by the Issuer/Processor funds would reflect in the respective funding source. Following are the properties of this endpoint.

Request Body schema: application/json
amount
number

This field contains the amount that was either loaded or unloaded from the funding source.

attachments
string

This field contains value in the "fileurl" field returned in the response of Raise Funding Document Upload API.

cardProgramUuid
string

This field contains the system generated unique identifier for the program that was created using the Create Card Program API.

purpose
string
Enum: "OTHER" "TRAVEL_AGENCY" "TRAVEL_MANAGEMENT_COMPANY" "DESTINATION_MANAGEMENT_COMPANY" "INSURANCE_THIRD_PARTY_ADMINISTRATOR" "INSURANCE_COMPANY" "TO_LOAD_THE_POOL_ACCOUNT"

This field contains the purpose of fundraising. Allowed value “OTHER”.

sourceFunds
string
Enum: "OTHER" "TRADING_ACTIVITIES" "RETAINED_PROFITS" "INVESTMENT"

This field contains the source of funds. Allowed value “OTHER”.

transactionType
string
Enum: "DEBIT" "CREDIT"

This field contains the transaction type (CREDIT to load the funds and DEBIT to unload the funds).

Responses

Request samples

Content type
application/json
{
  • "cardProgramUuid": "12z-126452",
  • "amount": 100,
  • "sourceFunds": "OTHER",
  • "attachments": "321",
  • "transactionType": "DEBIT",
  • "purpose": "OTHER"
}

Response samples

Content type
application/json
{
  • "status": "success"
}

Get Balance of Funding Source

The ‘Get Balance of Funding Source’ endpoint retrieves the remaining balance of a funding source. Following are the properties of this endpoint.

path Parameters
uuid
required
string <uuid>

This field contains the system generated unique identifier for the program that was created using the Create Card Program API.

Responses

Response samples

Content type
application/json
{
  • "amount": 100,
  • "currency": "PKR"
}

Card Program Merchant

The ‘Card Program Merchant’ API Group is designed so that the merchant controls can be enforced on the card programs. This API updates the Card Program Merchant controls either by blacklisting or whitelisting merchants.

Update Card Program Merchant

The ‘Update Card Program Merchant’ endpoint is used to either blacklist or whitelist the merchants. Transactions cannot be performed on the blacklisted merchants. Following are the properties of this endpoint.

path Parameters
uuid
required
string

This field contains a unique identifier of the card program.

Request Body schema: application/json
Array of objects

This array of objects lists the merchant Ids (MIDs) and MCCs to be blacklisted.

Array of objects

This array of objects lists the merchant Ids (MIDs) and MCCs to be whitelisted.

Responses

Request samples

Content type
application/json
{
  • "whiteList": [
    ],
  • "blackList": [
    ]
}

Company

The ‘Company’ API Group is designed to enable the 'Company' concept in the SimpliFi platform. The platform offers a multi-tenancy environment which enables it to host multiple clients (companies) concurrently with only physical resources being shared. This feature enables SimpliFi to enable their own dedicated set of conditions for each company, which ensures a safe and secure environment for their card programs.

The following list explains the general flow of hierarchy under each company:

  • At the top level, a company is created.
  • For each company, card programs can be created and managed.
  • For each card program, users (card holders) can be created and managed.
  • For each user, cards can be issued and managed.

Get a Card Design Image

The ‘Get a Card Design Image’ endpoint retrieves the image of the card design along with the content to be printed on the cards. Following are the properties of this endpoint.

path Parameters
uuid
required
string

This is an internal identifier of your company in the SimpliFi platform. We will generate the company name for you and share it. If you don't have it already, you can request it through this link.

query Parameters
fileType
string
Default: "IMAGE"

Company Logo or Card Image

Responses

Response samples

Content type
application/json
{
  • "uuid": "string",
  • "fileName": "string",
  • "fileContent": "string",
  • "fileType": "IMAGE"
}

Users

The ‘User’ API Group is designed to manage the users (card holders). It is mandatory that the cardholders should only be created under a card program. Card holder creation could be a one or two step process:

  • Capture user (card holders) details

  • Conduct user (card holders) KYC (if required by the regulators)

Requirements related to what user details need to be captured and the kind of KYC required are defined during client onboarding as mandated by the issuing bank and regulations, depending on the jurisdiction and the nature of the card program.

Following endpoints cover all the aspects of creating and maintaining users(card holders).

Retrieve a User

The ‘Retrieve a User’ endpoint retrieves details about an existing user (card holder). Following are the properties of this endpoint.

path Parameters
uuid
required
string <uuid>

This field contains a unique identifier of the user (card holder).

Responses

Response samples

Content type
application/json
{
  • "uuid": "f242acc1-bcbf-11eb-8529-c070bc3a2323",
  • "username": "johnsmith",
  • "firstName": "John",
  • "middleName": "M.",
  • "lastName": "Smith",
  • "gender": "MALE",
  • "email": "abc@xyz.com",
  • "userStatus": "ACTIVE",
  • "kycStatus": "ACTIVE",
  • "createdAt": "2021-05-15 18:00:00",
  • "token": "abc",
  • "userDetail": {
    },
  • "address": {
    },
  • "contact": [
    ]
}

Update a User

The ‘Update a User’ endpoint updates the details of an existing user (card holder). Following are the properties of this endpoint.

path Parameters
uuid
required
string <uuid>

This field contains a unique identifier of the user (card holder).

Request Body schema: application/json
object

Address

Array of objects

This array of objects is a collection of contact fields, possessing sub-fields explained in the rows below.

email
string

(deprecated) This is the email ID of the card holder.

firstName
required
string [ 1 .. 40 ] characters /^[a-zA-Z ]+/

This is the first name of the card holder.

gender
string
Enum: "MALE" "FEMALE"
lastName
required
string [ 1 .. 40 ] characters

This is the last name of the card holder.

middleName
string [ 1 .. 40 ] characters

This is the middle name of the card holder.

object

This object is a collection of user detail fields, possessing sub-fields explained in the rows below.

username
required
string [ 3 .. 40 ] characters

This is a unique identifier of the card holder in the system. We recommend providing a unique name here.

Responses

Request samples

Content type
application/json
{
  • "username": "johnsmith",
  • "firstName": "John",
  • "middleName": "M.",
  • "lastName": "Smith",
  • "gender": "MALE",
  • "email": "abc@xyz.com",
  • "userDetail": {
    },
  • "address": {
    },
  • "contact": [
    ]
}

Response samples

Content type
application/json
{
  • "uuid": "f242acc1-bcbf-11eb-8529-c070bc3a2323",
  • "username": "johnsmith",
  • "firstName": "John",
  • "middleName": "M.",
  • "lastName": "Smith",
  • "gender": "MALE",
  • "email": "abc@xyz.com",
  • "userStatus": "ACTIVE",
  • "kycStatus": "ACTIVE",
  • "createdAt": "2021-05-15 18:00:00",
  • "token": "abc",
  • "userDetail": {
    },
  • "address": {
    },
  • "contact": [
    ]
}

Delete a User

The ‘Delete a User’ endpoint deletes an existing user (card holder). Deleting a user (card holder) does not erase data from the system but only deactivates the user (card holder) and its associated cards. Following are the properties of this endpoint.

path Parameters
uuid
required
string <uuid>

This field contains a unique identifier of the user (card holder).

Responses

Add an Address

path Parameters
type
required
string

Address Type

uuid
required
string

User UUID

Request Body schema: application/json
address2
string

This field contains the second line of address of the card holder.

addressType
string
Enum: "PRIMARY" "DELIVERY"
cityCode
string

This field contains the city name of the card holder.

countryCode
string

This field contains the country code of the card holder.

postalCode
string

This field contains the postal code of the card holder.

stateCode
string

This field contains the state name of the card holder.

streetAddress
string

This field contains the street address of the card holder.

Responses

Request samples

Content type
application/json
{
  • "streetAddress": "Street 3, Phase 2, DHA.",
  • "addressType": "PRIMARY",
  • "cityCode": "KHI",
  • "stateCode": "SIND",
  • "countryCode": "PAK",
  • "postalCode": "75550",
  • "address2": "string"
}

Response samples

Content type
application/json
{
  • "uuid": "f242acc1-bcbf-11eb-8529-c070bc3a2323",
  • "streetAddress": "Street 3, Phase 2, DHA.",
  • "addressType": "PRIMARY",
  • "cityCode": "KHI",
  • "stateCode": "SIND",
  • "countryCode": "PAK",
  • "postalCode": "75550",
  • "address2": "string"
}

List all Users

The ‘List all Users’ endpoint retrieves all the existing users (card holders), grouped under a company. Following are the properties of this endpoint.

query Parameters
endDate
string

Represents the end date of the user’s registration with the Simplifi system. Note All the dates in the Simplifi system are stored and displayed in the following format "yyyy-mm-dd hh:mm:ss”

startDate
string

Represents the start date of the user’s registration with the Simplifi system. Note All the dates in the Simplifi system are stored and displayed in the following format "yyyy-mm-dd hh:mm:ss”

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a User

The ‘Create a User’ endpoint creates a new user (card holder). In the SimpliFi platform, it is mandatory for the card holders to be a part of a card program instead of being a standalone entity. It is mandatory to have a card holder created before issuing a card. Following are the properties of this endpoint.

Request Body schema: application/json
object

Address

Array of objects

This array of objects is a collection of contact fields, possessing sub-fields explained in the rows below.

email
string

(deprecated) This is the email ID of the card holder.

firstName
required
string [ 1 .. 40 ] characters /^[a-zA-Z ]+/

This is the first name of the card holder.

gender
string
Enum: "MALE" "FEMALE"
lastName
required
string [ 1 .. 40 ] characters

This is the last name of the card holder.

middleName
string [ 1 .. 40 ] characters

This is the middle name of the card holder.

object

This object is a collection of user detail fields, possessing sub-fields explained in the rows below.

username
required
string [ 3 .. 40 ] characters

This is a unique identifier of the card holder in the system. We recommend providing a unique name here.

Responses

Request samples

Content type
application/json
{
  • "username": "johnsmith",
  • "firstName": "John",
  • "middleName": "M.",
  • "lastName": "Smith",
  • "gender": "MALE",
  • "email": "abc@xyz.com",
  • "userDetail": {
    },
  • "address": {
    },
  • "contact": [
    ]
}

Response samples

Content type
application/json
{
  • "uuid": "f242acc1-bcbf-11eb-8529-c070bc3a2323",
  • "username": "johnsmith",
  • "firstName": "John",
  • "middleName": "M.",
  • "lastName": "Smith",
  • "gender": "MALE",
  • "email": "abc@xyz.com",
  • "userStatus": "ACTIVE",
  • "kycStatus": "ACTIVE",
  • "createdAt": "2021-05-15 18:00:00",
  • "token": "abc",
  • "userDetail": {
    },
  • "address": {
    },
  • "contact": [
    ]
}

Transactions

The ‘Transactions’ API Group is designed to allow you to have control over the listing of transactions that have been processed on a card. These endpoints enable you to get insights of different transactions being carried upon certain cards.

List All transactions

The 'List All Transactions' endpoint allows API users to retrieve a paginated array of all the transactions carried out in the last 90 days. The results are displayed with a default page size of 100 and the response returns the transaction list with total no. of elements. Following are the properties of this endpoint.

query Parameters
billAmount
number

Bill Amount

billCurrency
string

Bill Currency

cardProgramUuid
string

card uuid

cardUuid
string

card uuid

endDate
string

end date date of date-range

page
integer <int32>

page no

size
integer <int32>

size of page

startDate
string

start date of date-range

userUuid
string

user uuid

Responses

Response samples

Content type
application/json
{
  • "transactions": [
    ],
  • "totalElements": 145
}

List All Transactions

The ‘List All Transactions’ endpoint retrieves a paginated array of all the transactions carried out in the last 90 days. The results are displayed with a default page size of 100 and the response returns the transaction list with total no. of elements. Following are the properties of this endpoint.

Request Body schema: application/json
billAmount
number

This field contains the billed amount.

object
cardProgramUuids
Array of strings

These are unique identifiers of the card programs.

cardUuid
string

This is a unique identifier of the card.

endDate
string

This is the end date of transactions.

page
integer <int32>

This field contains the page number currently being displayed for transactions.

size
integer <int32>

This field contains the number of the transaction records to be displayed on this page.

sortBy
string
Enum: "transactionDate" "billAmount" "transactionAmount"
sortDirection
string
Enum: "ASC" "DESC"
startDate
string

This is the start date of transactions.

transactionType
Array of strings

This field defines the Transaction types. Allowed values are Auth (for Authorized transactions), Rev (for Reversed transactions), Settled (for Settled transactions), Refund (for Refund transactions), Load (for card load transactions), Unload (for card unload transactions).

userUuid
string

This is a unique identifier of the card holder.

Responses

Request samples

Content type
application/json
{
  • "cardProgramUuids": [
    ],
  • "page": 0,
  • "size": 0,
  • "startDate": "string",
  • "endDate": "string",
  • "cardUuid": "string",
  • "userUuid": "string",
  • "billAmount": 0,
  • "billCurrency": {
    },
  • "sortBy": "transactionDate",
  • "sortDirection": "ASC",
  • "transactionType": [
    ]
}

Response samples

Content type
application/json
{
  • "transactions": [
    ],
  • "totalElements": 145
}

Get Transaction by Uuid

The ‘Get Transactions by UUID’ endpoint retrieves a list of the transactions carried out by a card holder, using the Card UUID parameter. Following are the properties of this endpoint.

path Parameters
uuid
required
string

This is a unique identifier of the card.

Responses

Response samples

Content type
application/json
{
  • "transactionUuid": "11e082c2-993d-4026-82c4-1234ec464796",
  • "transactionId": "6615206",
  • "cardUuid": "11e082c2-993d-4026-82c4-1234ec464796",
  • "maskedPan": "************9999",
  • "userName": "muhammad",
  • "transactionType": "A",
  • "statusCode": "Accepted",
  • "mccCode": "5542",
  • "merchantId": "F09089372443345",
  • "merchantName": "GOOGLE *TEMPORARY HOLD",
  • "transactionAmount": 100,
  • "transactionCurrency": "SAR",
  • "transactionDate": "yyyy-MM-dd hh:mm:ss.nnn",
  • "billAmount": -6.95,
  • "billCurrency": "SAR"
}