ES SOLO API documentation API Reference

This is the ES SOLO API Developer-Knowledge Portal. Here you will find what functionality is available to you to integrate your ES SOLO account into your current and future business processes and to automate your business transactions.

To help you navigate, this page is split into 3 vertical sections:

  • the navigation menu on the left,
  • the content in the middle,
  • and usage examples on the right.

To get started, contact [email protected] to get the `x-api-key`. 

Note: all the currency amount(includes card balance, etc) is in `minor unit`(the `exponent`). See https://en.wikipedia.org/wiki/ISO_4217


Please DO NOT use production environment until you have tested your integration sufficiently and are happy that it works as expected.

API Endpoint
https://essolo.virtualcards.us/api
Terms of Service: https://essolo.virtualcards.us/sandbox-terms-of-service
Contact: [email protected]
Request Content-Types: application/x-www-form-urlencoded
Response Content-Types: application/json
Schemes: https
Version: 1.0.0

HTTP Headers

x-api-key

Used to verify api invoker. Value can has prefix 'Bearer '.

name
x-api-key
type
apiKey
in
header

x-token

User token. Get it by login API. Value can has prefix 'Bearer '.

name
x-token
type
apiKey
in
header

x-timezone

Not security requirement. User's timezone. Optional but highly recommend to add to specify date's timezone in request parameters. Default to be current user's timezone configure or America/New_York if x-token is not provided or timezone is not configured for the user. Value should be one of the timezone names listed in http://php.net/manual/en/timezones.php or an offset value (like +0200).

name
x-timezone
type
apiKey
in
header

x-i18n

Not security requirement. User's language to translate response message. Optional. Default to en. Valid values: en for English, zh for Chinese(中文(简体)), es for Spanish(Español), pt-BR for Brazilian Portuguese(Português do Brasil), ja for Japanese(にほんご), or ar for Arabic(العَرَبِيَّة).

name
x-i18n
type
apiKey
in
header

x-card-program

Not security requirement. Only required in the staging environment. This is the card program id which you are requesting in the staging environment for testing. Refer to the card programs API for more details.

name
x-card-program
type
apiKey
in
header

Basic data

Card programs

GET /card-programs

Get the card programs available for distribution to consumers, as well as product coverage-area details, and see general product-configuration settings. One of the most common uses of this particular API call is, determining the nestorProgramId that will be needed in subsequent Instant Registration posts.

Available card programs and related data. Save it so that you can call other APIs later.

400 Bad Request

Parameter error

401 Unauthorized

Authentication Required

403 Forbidden

Failed to authenticate

Response Example (200 OK)
{
    "success": "boolean",
    "message": "string",
    "data": [
        {
            "id": "integer",
            "name": "string",
            "supportDDA": "boolean",
            "supportExpense": "boolean",
            "cardsAllowed": "integer",
            "bin": "string",
            "deliveryMethod": "string",
            "kycProviderProgram": "string",
            "cards": [
                {
                    "id": "integer",
                    "name": "string",
                    "description": "string",
                    "benefit": "string",
                    "minLoadAmount": "number (float)",
                    "maxLoadAmount": "number (float)",
                    "maxBalance": "number (float)",
                    "currencies": [
                        "string"
                    ],
                    "artwork": "string",
                    "network": "string"
                }
            ],
            "countries": [
                {
                    "id": "integer",
                    "name": "string",
                    "iso": "string",
                    "iso3": "string",
                    "phoneCode": "string",
                    "region": "string"
                }
            ]
        }
    ]
}
Response Example (400 Bad Request)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}
Response Example (401 Unauthorized)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}
Response Example (403 Forbidden)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}

Provinces

GET /provinces

Get all provinces in the specified country

country: integer
in query

ISO country code, 3 characters

400 Bad Request

Parameter error

401 Unauthorized

Authentication Required

403 Forbidden

Failed to authenticate

Response Example (200 OK)
{
    "success": "boolean",
    "message": "string",
    "data": [
        {
            "id": "integer",
            "name": "string",
            "abbr": "string"
        }
    ]
}
Response Example (400 Bad Request)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}
Response Example (401 Unauthorized)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}
Response Example (403 Forbidden)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}

Query result

GET /query-result

Query an old request's result according to the specified requestId

requestId: string
in query

Unique ID for the request.

200 OK

400 Bad Request

Parameter error

401 Unauthorized

Authentication Required

403 Forbidden

Failed to authenticate

Response Example (200 OK)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}
Response Example (400 Bad Request)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}
Response Example (401 Unauthorized)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}
Response Example (403 Forbidden)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}

Instant registration

Instant Registration

POST /essolo/register/instant

The intent of the register/instant API call is to perform KYC and onboarding in a single pass (assuming the customer did not fail KYC).


In the event of a KYC failure, the user can reupload the needed documents/settings and settings as needed to rectify the matter using the Resubmit registration KYC call.


To derive the residenceStateProvinceId & shippingStateProvinceId you must first perform a provinces call to look up the information using its respective country code.


Retain the following values for subsequent ES SOLO API calls:


  • registrationRequestId - a unique identifier provided by the Program Owner to lookup Instant Registration attempts and segment card orders.
  • userCardId - a unique identifier for the card issued, to the customer, on the ES SOLO platform, to use in API calls.
  • userToken - a unique token to authorize update to records, for the underlying customer, in API calls.

registrationRequestId: integer
in formData

Unique ID for the request, from the Product Owner/Brand Partner, used to enforce idempotency in the Registration API.

If registrationRequestId has been provided by the API Invoker and isKycUpdate = False. Replay the exact previous API response for the registrationRequestId (for idepotance).

If the request ID has been provided by the API Invoker and isKYCUpdate = True & userID has a kycStatus of ‘KYC Failed’ - try to see if the data provided/updated for the request is sufficient to get a pass from Nestor.

If above = yes, continue with card registration.

If above = no, Error = ‘Sorry, this customer has not passed KYC, please resubmit revised KYC data using the same registrationRequestId from the initial request, and set isKycUpdate to True and resubmit KYC info.’

nestorProgramId: integer
in formData

Card Program ID found in the nestor system.
We will store this at the product level. We will obfuscate the Tern Platform Card ID from Program Owners and use the nestorProgramId in API communications, as an attempt to prevent unnecessary confusion.

(use this as lookup to determine if the product requires shipping or not. If the card does not require shipping - the correct Card Program ID is validated to ensure it matches the inventory record in the table correctly. In the event of a Program ID mismatch Error = ‘Program ID mismatch, please try again.')

Note: API Invoker can run the existing Card Programs API call to see what program IDs they have ability to select from.

isKycUpdate: boolean
in formData

True or False.

If True and User Status = KYC Failed - allow for a resubmission of KYC data to see if it passes. If it passes - continue with registration flow.

If it result = False, remain in KYC Failed Status but count the attempts (see output for failedKycAttempts field).

cardProcessorUniqueId: integer
in formData

An example of the unique id’s used to correlate to a given card, for a registered cardholder, per individual processors supported (connectivity wise) today are:

  • GTP = Customer ID
  • NI = Client ID

cardShippingMethod: integer
in formData

1 = standard, 2 = priority, 3 = rush delivery, 4 = registered mail [default = 1/standard]

firstName: string
in formData

First name

lastName: string
in formData

Last name

birthday: string (date)
in formData

Date of birth. Format: YYYY-MM-DD

gender: string
in formData

Gender, Male or Female

emailAddress: string (email)
in formData

Email address

residenceAddress: string
in formData

First address line

residenceAddress2: string
in formData

Second address line

residenceCountryId: string
in formData

ISO country code, 3 characters

residenceStateProvinceId: integer
in formData

Province Id. See the /provinces API.

residenceCity: string
in formData

City name

residencePostalCode: string
in formData

Zip/Postal code

homePhone: string
in formData

Home phone

mobilePhone: string
in formData

Mobile phone

workPhone: string
in formData

Work phone

proofAddressTypeId: integer
in formData

Proof type of your address. Available values: 1 - Utility Bill, 2 - Driver's License, 3 - Passport, 4 - National ID, 5 - Property Tax Receipt, 6 - Lease Agreement, 7 - Insurance Card, 8 - Landline Phone Statement, 9 - Bank Statement, 10 - Other

proofOfAddress: string
in formData

Base64 string of your address proof file. Only support .jpg, .png and .pdf files. Optional if proofOfAddressFile is provided.

proofOfAddressFile: file
in formData

Address proof file. Only support .jpg, .png and .pdf files. Optional and will be ignored if proofOfAddress is provided.

shippingAddress1: string
in formData

The place that the card will be shipped. This will only be required on shipped programs.

shippingAddress2: string
in formData

Shipping Address Line 2

shippingCountryId: string
in formData

ISO country code, 3 characters

shippingCountry: string
in formData

Shipping Country Name

shippingStateProvinceId: string
in formData

Province Id. See the /provinces API.

shippingCity: string
in formData

City Name

shippingPostalCode: string
in formData

Postal Code

idTypeId: integer
in formData

Available values: 1 - Driver's License, 2 - National ID, 3 - Passport, 4 - Social Security Card, 5 - Birth Certificate

idUpload: string
in formData

Base64 string of your id file. Only support .jpg, .png and .pdf files. Optional if idUploadFile is provided.

idUploadFile: file
in formData

Id file. Only support .jpg, .png and .pdf files. Optional and will be ignored if idUpload is provided.

ssn: string
in formData

Reqruied if you are in United States.

driverLicenseNo: string
in formData

Required if IDTypeID is 1

passportNumber: string
in formData

Required if IDTypeID is 3

countryOfPassport: string
in formData

Required if IDTypeID is 3. Country's full name. See card programs API for more details.

nationalId: string
in formData

Required if IDTypeID is other than 1 and 3.

400 Bad Request

Parameter error

401 Unauthorized

Authentication Required

403 Forbidden

Failed to authenticate

Response Example (200 OK)
{
    "success": "boolean",
    "message": "string",
    "data": {
        "registrationRequestId": "integer",
        "submissonDateTime": "date",
        "programOwnerId": "string",
        "programOwnerName": "string",
        "nestorProgramId": "integer",
        "programName": "string",
        "issuingBankId": "integer",
        "issuingBankName": "string",
        "cardProcessor": "string",
        "isRegistered": "boolean",
        "registrationDateTime": "date",
        "userCardId": "integer",
        "cardRegistrationKey": "string",
        "cardCreationDate": "date",
        "cardStatus": "string",
        "cardCurrency": "string",
        "bin": "integer",
        "cardProcessorUniqueId": "integer",
        "cardShippingMethod": "integer",
        "shippingAddress1": "string",
        "shippingAddress2": "string",
        "shippingCountryId": "string",
        "shippingCountry": "string",
        "shippingStateProvinceId": "string",
        "shippingCity": "string",
        "shippingPostalCode": "string",
        "userID": "integer",
        "userToken": "string",
        "kycPassed": "boolean",
        "failedKycAttempts": "integer",
        "kycApprovedDate": "date",
        "firstName": "string",
        "lastName": "string",
        "birthday": "string (date)",
        "gender": "string",
        "emailAddress": "string (email)",
        "residenceAddress": "string",
        "residenceAddress2": "string",
        "residenceCountryId": "string",
        "residenceCountryName": "string",
        "residenceStateProvinceId": "integer",
        "residenceCity": "string",
        "residencePostalCode": "string",
        "homePhone": "string",
        "mobilephone": "string",
        "workphone": "string",
        "proofAddressType": "string",
        "proofOfAddress": "string",
        "idTypeId": "string",
        "idUpload": "string",
        "ssn": "string",
        "driversLicenseNo": "string",
        "passportNumber": "string",
        "countryOfPassport": "string",
        "nationalId": "string",
        "lastErrorMessage": "string"
    }
}
Response Example (400 Bad Request)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}
Response Example (401 Unauthorized)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}
Response Example (403 Forbidden)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}

Query registration

GET /essolo/register/instant

The GET call will enable the ability to check the status on a given Instant Registration using an ES SOLO registrationRequestId (as the lookup value) for a given API Invoker.

registrationRequestId: integer
in formData

Unique ID for a request from a particular API Invoker, from the Product Owner/Brand Partner, used to enforce idempotency in the Registration API.

400 Bad Request

Parameter error

401 Unauthorized

Authentication Required

403 Forbidden

Failed to authenticate

Response Example (200 OK)
{
    "success": "boolean",
    "message": "string",
    "data": {
        "registrationRequestId": "integer",
        "submissonDateTime": "date",
        "programOwnerId": "string",
        "programOwnerName": "string",
        "nestorProgramId": "integer",
        "programName": "string",
        "issuingBankId": "integer",
        "issuingBankName": "string",
        "cardProcessor": "string",
        "isRegistered": "boolean",
        "registrationDateTime": "date",
        "userCardId": "integer",
        "cardRegistrationKey": "string",
        "cardCreationDate": "date",
        "cardStatus": "string",
        "cardCurrency": "string",
        "bin": "integer",
        "cardProcessorUniqueId": "integer",
        "cardShippingMethod": "integer",
        "shippingAddress1": "string",
        "shippingAddress2": "string",
        "shippingCountryId": "string",
        "shippingCountry": "string",
        "shippingStateProvinceId": "string",
        "shippingCity": "string",
        "shippingPostalCode": "string",
        "userID": "integer",
        "userToken": "string",
        "kycPassed": "boolean",
        "failedKycAttempts": "integer",
        "kycApprovedDate": "date",
        "firstName": "string",
        "lastName": "string",
        "birthday": "string (date)",
        "gender": "string",
        "emailAddress": "string (email)",
        "residenceAddress": "string",
        "residenceAddress2": "string",
        "residenceCountryId": "string",
        "residenceCountryName": "string",
        "residenceStateProvinceId": "integer",
        "residenceCity": "string",
        "residencePostalCode": "string",
        "homePhone": "string",
        "mobilephone": "string",
        "workphone": "string",
        "proofAddressType": "string",
        "proofOfAddress": "string",
        "idTypeId": "string",
        "idUpload": "string",
        "ssn": "string",
        "driversLicenseNo": "string",
        "passportNumber": "string",
        "countryOfPassport": "string",
        "nationalId": "string",
        "lastErrorMessage": "string"
    }
}
Response Example (400 Bad Request)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}
Response Example (401 Unauthorized)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}
Response Example (403 Forbidden)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}

Resubmit registration KYC

POST /essolo/register/instant

  • Most parameters and responses are same as the Instant Registration API.
  • Please use the same registrationRequestId.
  • Set isKycUpdate to True.

The intent of the register/instant API call is to perform KYC and onboarding in a single pass (assuming the customer did not fail KYC).

In the event of a KYC failure, the user can re-upload the needed documents\/settings and settings as needed to rectify the matter.

If the KYC is approved successfully upon resubmission, the response will include a valid userCardId and userToken. It is suggested as a best practice, that your application retain those values, to use in subsequent API calls, if/as needed.

registrationRequestId: integer
in formData

Unique ID for the request, from the Product Owner/Brand Partner, used to enforce idempotency in the Registration API.

If registrationRequestId has been provided by the API Invoker and isKycUpdate = False. Replay the exact previous API response for the registrationRequestId (for idepotance).

If the request ID has been provided by the API Invoker and isKYCUpdate = True & userID has a kycStatus of ‘KYC Failed’ - try to see if the data provided/updated for the request is sufficient to get a pass from Nestor.

If above = yes, continue with card registration.

If above = no, Error = ‘Sorry, this customer has not passed KYC, please resubmit revised KYC data using the same registrationRequestId from the initial request, and set isKycUpdate to True and resubmit KYC info.’

nestorProgramId: integer
in formData

Card Program ID found in the nestor system.
We will store this at the product level. We will obfuscate the Tern Platform Card ID from Program Owners and use the nestorProgramId in API communications, as an attempt to prevent unnecessary confusion.

(use this as lookup to determine if the product requires shipping or not. If the card does not require shipping - the correct Card Program ID is validated to ensure it matches the inventory record in the table correctly. In the event of a Program ID mismatch Error = ‘Program ID mismatch, please try again.')

Note: API Invoker can run the existing Card Programs API call to see what program IDs they have ability to select from.

isKycUpdate: boolean
in formData

True or False.

If True and User Status = KYC Failed - allow for a resubmission of KYC data to see if it passes. If it passes - continue with registration flow.

If it result = False, remain in KYC Failed Status but count the attempts (see output for failedKycAttempts field).

cardProcessorUniqueId: integer
in formData

An example of the unique id’s used to correlate to a given card, for a registered cardholder, per individual processors supported (connectivity wise) today are:

  • GTP = Customer ID
  • NI = Client ID

cardShippingMethod: integer
in formData

1 = standard, 2 = priority, 3 = rush delivery, 4 = registered mail [default = 1/standard]

firstName: string
in formData

First name

lastName: string
in formData

Last name

birthday: string (date)
in formData

Date of birth. Format: YYYY-MM-DD

gender: string
in formData

Gender, Male or Female

emailAddress: string (email)
in formData

Email address

residenceAddress: string
in formData

First address line

residenceAddress2: string
in formData

Second address line

residenceCountryId: string
in formData

ISO country code, 3 characters

residenceStateProvinceId: integer
in formData

Province Id. See the /provinces API.

residenceCity: string
in formData

City name

residencePostalCode: string
in formData

Zip/Postal code

homePhone: string
in formData

Home phone

mobilePhone: string
in formData

Mobile phone

workPhone: string
in formData

Work phone

proofAddressTypeId: integer
in formData

Proof type of your address. Available values: 1 - Utility Bill, 2 - Driver's License, 3 - Passport, 4 - National ID, 5 - Property Tax Receipt, 6 - Lease Agreement, 7 - Insurance Card, 8 - Landline Phone Statement, 9 - Bank Statement, 10 - Other

proofOfAddress: string
in formData

Base64 string of your address proof file. Only support .jpg, .png and .pdf files. Optional if proofOfAddressFile is provided.

proofOfAddressFile: file
in formData

Address proof file. Only support .jpg, .png and .pdf files. Optional and will be ignored if proofOfAddress is provided.

shippingAddress1: string
in formData

The place that the card will be shipped. This will only be required on shipped programs.

shippingAddress2: string
in formData

Shipping Address Line 2

shippingCountryId: string
in formData

ISO country code, 3 characters

shippingCountry: string
in formData

Shipping Country Name

shippingStateProvinceId: string
in formData

Province Id. See the /provinces API.

shippingCity: string
in formData

City Name

shippingPostalCode: string
in formData

Postal Code

idTypeId: integer
in formData

Available values: 1 - Driver's License, 2 - National ID, 3 - Passport, 4 - Social Security Card, 5 - Birth Certificate

idUpload: string
in formData

Base64 string of your id file. Only support .jpg, .png and .pdf files. Optional if idUploadFile is provided.

idUploadFile: file
in formData

Id file. Only support .jpg, .png and .pdf files. Optional and will be ignored if idUpload is provided.

ssn: string
in formData

Reqruied if you are in United States.

driverLicenseNo: string
in formData

Required if IDTypeID is 1

passportNumber: string
in formData

Required if IDTypeID is 3

countryOfPassport: string
in formData

Required if IDTypeID is 3. Country's full name. See card programs API for more details.

nationalId: string
in formData

Required if IDTypeID is other than 1 and 3.

400 Bad Request

Parameter error

401 Unauthorized

Authentication Required

403 Forbidden

Failed to authenticate

Response Example (200 OK)
{
    "success": "boolean",
    "message": "string",
    "data": {
        "registrationRequestId": "integer",
        "submissonDateTime": "date",
        "programOwnerId": "string",
        "programOwnerName": "string",
        "nestorProgramId": "integer",
        "programName": "string",
        "issuingBankId": "integer",
        "issuingBankName": "string",
        "cardProcessor": "string",
        "isRegistered": "boolean",
        "registrationDateTime": "date",
        "userCardId": "integer",
        "cardRegistrationKey": "string",
        "cardCreationDate": "date",
        "cardStatus": "string",
        "cardCurrency": "string",
        "bin": "integer",
        "cardProcessorUniqueId": "integer",
        "cardShippingMethod": "integer",
        "shippingAddress1": "string",
        "shippingAddress2": "string",
        "shippingCountryId": "string",
        "shippingCountry": "string",
        "shippingStateProvinceId": "string",
        "shippingCity": "string",
        "shippingPostalCode": "string",
        "userID": "integer",
        "userToken": "string",
        "kycPassed": "boolean",
        "failedKycAttempts": "integer",
        "kycApprovedDate": "date",
        "firstName": "string",
        "lastName": "string",
        "birthday": "string (date)",
        "gender": "string",
        "emailAddress": "string (email)",
        "residenceAddress": "string",
        "residenceAddress2": "string",
        "residenceCountryId": "string",
        "residenceCountryName": "string",
        "residenceStateProvinceId": "integer",
        "residenceCity": "string",
        "residencePostalCode": "string",
        "homePhone": "string",
        "mobilephone": "string",
        "workphone": "string",
        "proofAddressType": "string",
        "proofOfAddress": "string",
        "idTypeId": "string",
        "idUpload": "string",
        "ssn": "string",
        "driversLicenseNo": "string",
        "passportNumber": "string",
        "countryOfPassport": "string",
        "nationalId": "string",
        "lastErrorMessage": "string"
    }
}
Response Example (400 Bad Request)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}
Response Example (401 Unauthorized)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}
Response Example (403 Forbidden)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}

Card information

Card detail

GET /card/detail

Check a specific card's balance for a user using a retained ES SOLO userCardId.

userCardId: integer
in query

The card want to check balance. It should be the value of userCardId field in result of member info API. See Card Programs API and Member Info API

refresh: boolean
in query

Whether to get latest card balance.

400 Bad Request

Parameter error

401 Unauthorized

Authentication Required

403 Forbidden

Failed to authenticate

Response Example (200 OK)
{
    "success": "boolean",
    "message": "string",
    "data": {
        "id": "integer",
        "card": {
            "id": "integer",
            "name": "string",
            "description": "string",
            "benefit": "string",
            "minLoadAmount": "number (float)",
            "maxLoadAmount": "number (float)",
            "maxBalance": "number (float)",
            "currencies": [
                "string"
            ],
            "artwork": "string",
            "network": "string"
        },
        "hash": "string",
        "pan": "string",
        "holder": "string",
        "balance": "integer",
        "currency": "string",
        "coin": {
            "amount": "integer",
            "currency": "string",
            "formatted": "string",
            "symbol": "string,"
        },
        "status": "string",
        "issued": "boolean",
        "lastTransaction": {
            "id": "integer",
            "tranId": "string",
            "amount": "integer",
            "currency": "string",
            "coin": {
                "amount": "integer",
                "currency": "string",
                "formatted": "string",
                "symbol": "string,"
            },
            "balance": {
                "amount": "integer",
                "currency": "string",
                "formatted": "string",
                "symbol": "string,"
            },
            "time": "string (date)",
            "merchant": {
                "id": "integer",
                "name": "string",
                "type": "string",
                "mcc": "string",
                "list": "string"
            },
            "type": "string",
            "description": "string",
            "order": "integer"
        }
    }
}
Response Example (400 Bad Request)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}
Response Example (401 Unauthorized)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}
Response Example (403 Forbidden)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}

Card Transactions

GET /essolo/transactions

Check a specific card's transaction history for a user, using a retained ES SOLO userCardId.

userCardId: integer
in query

The card want to check transaction history. It should be the value of 'userCardId' field in result of member info or card list APIs

startAt: string (date)
in query

Start date filter. Format: YYYY-MM-DD

endAt: string (date)
in query

End date filter. Format: YYYY-MM-DD

number: integer
in query

Max transactions to return. Defaults to 100

400 Bad Request

Parameter error

401 Unauthorized

Authentication Required

403 Forbidden

Failed to authenticate

Response Example (200 OK)
{
    "success": "boolean",
    "message": "string",
    "data": [
        {
            "id": "integer",
            "tranId": "string",
            "amount": "integer",
            "currency": "string",
            "coin": {
                "amount": "integer",
                "currency": "string",
                "formatted": "string",
                "symbol": "string,"
            },
            "balance": {
                "amount": "integer",
                "currency": "string",
                "formatted": "string",
                "symbol": "string,"
            },
            "time": "string (date)",
            "merchant": {
                "id": "integer",
                "name": "string",
                "type": "string",
                "mcc": "string",
                "list": "string"
            },
            "type": "string",
            "description": "string",
            "order": "integer"
        }
    ]
}
Response Example (400 Bad Request)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}
Response Example (401 Unauthorized)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}
Response Example (403 Forbidden)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}

Status changes

Activate card

POST /card/activate

The status change will be synced to the card issuer using a retained ES SOLO userCardId.

requestId: string
in formData

Unique ID for the request. It will be returned in the response. You can query the result of previous request with the same requestId and GET method. This parameter is optional but recommended.

userCardId: integer
in formData

The card want to update status. It should be the value of userCardId field in result of member info API. See Card Programs API and Member Info API

200 OK

400 Bad Request

Parameter error

401 Unauthorized

Authentication Required

403 Forbidden

Failed to authenticate

Response Example (200 OK)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}
Response Example (400 Bad Request)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}
Response Example (401 Unauthorized)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}
Response Example (403 Forbidden)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}

Inactivate card

POST /card/inactivate

Status will be synced to card issuer. Balance will be unloaded if the unload parameter is true.

requestId: string
in formData

Unique ID for the request. It will be returned in the response. You can query the result of previous request with the same requestId and GET method. This parameter is optional but recommended.

userCardId: integer
in formData

The card want to update status. It should be the value of userCardId field in result of member info API. See Card Programs API and Member Info API

unload: boolean
in formData

Whether to unload the card before deactivating it.

200 OK

400 Bad Request

Parameter error

401 Unauthorized

Authentication Required

403 Forbidden

Failed to authenticate

Response Example (200 OK)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}
Response Example (400 Bad Request)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}
Response Example (401 Unauthorized)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}
Response Example (403 Forbidden)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}

Close card

POST /card/close

Status will be synced to card issuer. Balance will be unloaded. The user is able to register another card.

requestId: string
in formData

Unique ID for the request. It will be returned in the response. You can query the result of previous request with the same requestId and GET method. This parameter is optional but recommended.

userCardId: integer
in formData

The card want to update status.

200 OK

400 Bad Request

Parameter error

401 Unauthorized

Authentication Required

403 Forbidden

Failed to authenticate

Response Example (200 OK)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}
Response Example (400 Bad Request)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}
Response Example (401 Unauthorized)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}
Response Example (403 Forbidden)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}

Balance adjustments

Load card

POST /essolo/load

Load the user's card with a specified amount using a retained ES SOLO userCardId.

requestId: string
in formData

Unique ID for the request. It will be returned in the response. You can query the result of previous request with the same requestId and GET method. This parameter is optional but recommended.

userCardId: integer
in formData

The card want to load.

amount: number (integer) x ≥ 1
in formData

Load amount(minor unit) in card's currency. Currency code can be found in the response of the card detail API.

200 OK

400 Bad Request

Parameter error

401 Unauthorized

Authentication Required

403 Forbidden

Failed to authenticate

Response Example (200 OK)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}
Response Example (400 Bad Request)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}
Response Example (401 Unauthorized)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}
Response Example (403 Forbidden)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}

Unload card

POST /essolo/unload

Unload the user's card with a specified amount using a retained ES SOLO userCardId.

requestId: string
in formData

Unique ID for the request. It will be returned in the response. You can query the result of previous request with the same requestId and GET method. This parameter is optional but recommended.

userCardId: integer
in formData

The card want to unload.

amount: number (integer) x ≥ 1
in formData

Unload amount(minor unit) in card's currency. Currency code can be found in the response of the card detail API.

200 OK

400 Bad Request

Parameter error

401 Unauthorized

Authentication Required

403 Forbidden

Failed to authenticate

Response Example (200 OK)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}
Response Example (400 Bad Request)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}
Response Example (401 Unauthorized)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}
Response Example (403 Forbidden)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}

Card to card transfer

POST /essolo/transfer

Transfer a specified amount from a card's balance to another.

requestId: string
in formData

Unique ID for the request. It will be returned in the response. You can query the result of previous request with the same requestId and GET method. This parameter is optional but recommended.

fromUserCardId: integer
in formData

The sending user card Id

toUserCardId: integer
in formData

The receiving user card Id

amount: number (integer) x ≥ 1
in formData

The amount to transfer in fromUserCard's currency. Currency code can be found in the response of the fromUserCard's detail API. It cannot exceed the balance of the sending user card.

200 OK

400 Bad Request

Parameter error

401 Unauthorized

Authentication Required

403 Forbidden

Failed to authenticate

Response Example (200 OK)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}
Response Example (400 Bad Request)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}
Response Example (401 Unauthorized)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}
Response Example (403 Forbidden)
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}

Schema Definitions

Response: object

success: boolean

Operation failed or not

message: string

Error or success message

data: object

Operation Result

Example
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}

CardProgramsResponse: object

success: boolean

message: string

data: CardProgram
CardProgram

Example
{
    "success": "boolean",
    "message": "string",
    "data": [
        {
            "id": "integer",
            "name": "string",
            "supportDDA": "boolean",
            "supportExpense": "boolean",
            "cardsAllowed": "integer",
            "bin": "string",
            "deliveryMethod": "string",
            "kycProviderProgram": "string",
            "cards": [
                {
                    "id": "integer",
                    "name": "string",
                    "description": "string",
                    "benefit": "string",
                    "minLoadAmount": "number (float)",
                    "maxLoadAmount": "number (float)",
                    "maxBalance": "number (float)",
                    "currencies": [
                        "string"
                    ],
                    "artwork": "string",
                    "network": "string"
                }
            ],
            "countries": [
                {
                    "id": "integer",
                    "name": "string",
                    "iso": "string",
                    "iso3": "string",
                    "phoneCode": "string",
                    "region": "string"
                }
            ]
        }
    ]
}

ProvincesResponse: object

success: boolean

message: string

data: State
State

Example
{
    "success": "boolean",
    "message": "string",
    "data": [
        {
            "id": "integer",
            "name": "string",
            "abbr": "string"
        }
    ]
}

CardDetailResponse: object

success: boolean

message: string

data: UserCard

Example
{
    "success": "boolean",
    "message": "string",
    "data": {
        "id": "integer",
        "card": {
            "id": "integer",
            "name": "string",
            "description": "string",
            "benefit": "string",
            "minLoadAmount": "number (float)",
            "maxLoadAmount": "number (float)",
            "maxBalance": "number (float)",
            "currencies": [
                "string"
            ],
            "artwork": "string",
            "network": "string"
        },
        "hash": "string",
        "pan": "string",
        "holder": "string",
        "balance": "integer",
        "currency": "string",
        "coin": {
            "amount": "integer",
            "currency": "string",
            "formatted": "string",
            "symbol": "string,"
        },
        "status": "string",
        "issued": "boolean",
        "lastTransaction": {
            "id": "integer",
            "tranId": "string",
            "amount": "integer",
            "currency": "string",
            "coin": {
                "amount": "integer",
                "currency": "string",
                "formatted": "string",
                "symbol": "string,"
            },
            "balance": {
                "amount": "integer",
                "currency": "string",
                "formatted": "string",
                "symbol": "string,"
            },
            "time": "string (date)",
            "merchant": {
                "id": "integer",
                "name": "string",
                "type": "string",
                "mcc": "string",
                "list": "string"
            },
            "type": "string",
            "description": "string",
            "order": "integer"
        }
    }
}

UserCard: object

id: integer

card: CardProgramCardType

hash: string

pan: string

May be null

holder: string

May be null

balance: integer

May be null

currency: string

coin: Coin

status: string active, inactive

inactive status also means closed

issued: boolean

lastTransaction: UserCardTransaction

May be null

Example
{
    "id": "integer",
    "card": {
        "id": "integer",
        "name": "string",
        "description": "string",
        "benefit": "string",
        "minLoadAmount": "number (float)",
        "maxLoadAmount": "number (float)",
        "maxBalance": "number (float)",
        "currencies": [
            "string"
        ],
        "artwork": "string",
        "network": "string"
    },
    "hash": "string",
    "pan": "string",
    "holder": "string",
    "balance": "integer",
    "currency": "string",
    "coin": {
        "amount": "integer",
        "currency": "string",
        "formatted": "string",
        "symbol": "string,"
    },
    "status": "string",
    "issued": "boolean",
    "lastTransaction": {
        "id": "integer",
        "tranId": "string",
        "amount": "integer",
        "currency": "string",
        "coin": {
            "amount": "integer",
            "currency": "string",
            "formatted": "string",
            "symbol": "string,"
        },
        "balance": {
            "amount": "integer",
            "currency": "string",
            "formatted": "string",
            "symbol": "string,"
        },
        "time": "string (date)",
        "merchant": {
            "id": "integer",
            "name": "string",
            "type": "string",
            "mcc": "string",
            "list": "string"
        },
        "type": "string",
        "description": "string",
        "order": "integer"
    }
}

CardTransactionHistoryResponse: object

success: boolean

message: string

data: UserCardTransaction
UserCardTransaction

Example
{
    "success": "boolean",
    "message": "string",
    "data": [
        {
            "id": "integer",
            "tranId": "string",
            "amount": "integer",
            "currency": "string",
            "coin": {
                "amount": "integer",
                "currency": "string",
                "formatted": "string",
                "symbol": "string,"
            },
            "balance": {
                "amount": "integer",
                "currency": "string",
                "formatted": "string",
                "symbol": "string,"
            },
            "time": "string (date)",
            "merchant": {
                "id": "integer",
                "name": "string",
                "type": "string",
                "mcc": "string",
                "list": "string"
            },
            "type": "string",
            "description": "string",
            "order": "integer"
        }
    ]
}

CardProgram: object

id: integer

name: string

supportDDA: boolean

supportExpense: boolean

cardsAllowed: integer

The max cards user can hold. 0 means no limit.

bin: string

6-8 digit BIN of a card

deliveryMethod: string

hand = Hand to customer directly (instant issue), while mail = Mail to customer (requires shipping)

kycProviderProgram: string

Program Id of the KYC Provider if required

cards: CardProgramCardType
CardProgramCardType

countries: Country
Country

Example
{
    "id": "integer",
    "name": "string",
    "supportDDA": "boolean",
    "supportExpense": "boolean",
    "cardsAllowed": "integer",
    "bin": "string",
    "deliveryMethod": "string",
    "kycProviderProgram": "string",
    "cards": [
        {
            "id": "integer",
            "name": "string",
            "description": "string",
            "benefit": "string",
            "minLoadAmount": "number (float)",
            "maxLoadAmount": "number (float)",
            "maxBalance": "number (float)",
            "currencies": [
                "string"
            ],
            "artwork": "string",
            "network": "string"
        }
    ],
    "countries": [
        {
            "id": "integer",
            "name": "string",
            "iso": "string",
            "iso3": "string",
            "phoneCode": "string",
            "region": "string"
        }
    ]
}

CardProgramCardType: object

id: integer

name: string

description: string

benefit: string

minLoadAmount: number (float)

Minimum load amount in USD cents

maxLoadAmount: number (float)

Maximum load amount in USD cents

maxBalance: number (float)

Minimum card balance in USD cents

currencies: string[]
string

artwork: string

Card's image url

network: string visa, master

Visa or MasterCard

Example
{
    "id": "integer",
    "name": "string",
    "description": "string",
    "benefit": "string",
    "minLoadAmount": "number (float)",
    "maxLoadAmount": "number (float)",
    "maxBalance": "number (float)",
    "currencies": [
        "string"
    ],
    "artwork": "string",
    "network": "string"
}

Country: object

id: integer

name: string

iso: string

ISO code (2 characters), for instance, US

iso3: string

ISO code (3 characters), for instance, USA

phoneCode: string

region: string EMEA, AMERICAS, APAC,

Example
{
    "id": "integer",
    "name": "string",
    "iso": "string",
    "iso3": "string",
    "phoneCode": "string",
    "region": "string"
}

State: object

id: integer

name: string

abbr: string

Example
{
    "id": "integer",
    "name": "string",
    "abbr": "string"
}

UserCardTransaction: object

id: integer

tranId: string

Internal transaction ID

amount: integer

currency: string

coin: Coin

balance: Coin

time: string (date)

merchant: Merchant

May be null

type: string Credet, Debit

description: string

order: integer

Transaction order of the user card. Start from 1. Only count for POS purchase(00040) May be null

Example
{
    "id": "integer",
    "tranId": "string",
    "amount": "integer",
    "currency": "string",
    "coin": {
        "amount": "integer",
        "currency": "string",
        "formatted": "string",
        "symbol": "string,"
    },
    "balance": {
        "amount": "integer",
        "currency": "string",
        "formatted": "string",
        "symbol": "string,"
    },
    "time": "string (date)",
    "merchant": {
        "id": "integer",
        "name": "string",
        "type": "string",
        "mcc": "string",
        "list": "string"
    },
    "type": "string",
    "description": "string",
    "order": "integer"
}

Merchant: object

id: integer

name: string

type: string

mcc: string

list: string White, Grey, Restricted

May be null

Example
{
    "id": "integer",
    "name": "string",
    "type": "string",
    "mcc": "string",
    "list": "string"
}

Coin: object

amount: integer

Minor unit of the currency

currency: string

ISO currency code

formatted: string

Formatted amount text in primary unit

symbol: string,

Currency symbol

Example
{
    "amount": "integer",
    "currency": "string",
    "formatted": "string",
    "symbol": "string,"
}

EsSoloInstantRegistrationResponse: object

success: boolean

True or False if Registration was successful.
(see message field for human readable detailed response)

message: string

Human readable success or error message depending on if the success field (above at the top of this section) = true or false.

data: object

Example
{
    "success": "boolean",
    "message": "string",
    "data": {
        "registrationRequestId": "integer",
        "submissonDateTime": "date",
        "programOwnerId": "string",
        "programOwnerName": "string",
        "nestorProgramId": "integer",
        "programName": "string",
        "issuingBankId": "integer",
        "issuingBankName": "string",
        "cardProcessor": "string",
        "isRegistered": "boolean",
        "registrationDateTime": "date",
        "userCardId": "integer",
        "cardRegistrationKey": "string",
        "cardCreationDate": "date",
        "cardStatus": "string",
        "cardCurrency": "string",
        "bin": "integer",
        "cardProcessorUniqueId": "integer",
        "cardShippingMethod": "integer",
        "shippingAddress1": "string",
        "shippingAddress2": "string",
        "shippingCountryId": "string",
        "shippingCountry": "string",
        "shippingStateProvinceId": "string",
        "shippingCity": "string",
        "shippingPostalCode": "string",
        "userID": "integer",
        "userToken": "string",
        "kycPassed": "boolean",
        "failedKycAttempts": "integer",
        "kycApprovedDate": "date",
        "firstName": "string",
        "lastName": "string",
        "birthday": "string (date)",
        "gender": "string",
        "emailAddress": "string (email)",
        "residenceAddress": "string",
        "residenceAddress2": "string",
        "residenceCountryId": "string",
        "residenceCountryName": "string",
        "residenceStateProvinceId": "integer",
        "residenceCity": "string",
        "residencePostalCode": "string",
        "homePhone": "string",
        "mobilephone": "string",
        "workphone": "string",
        "proofAddressType": "string",
        "proofOfAddress": "string",
        "idTypeId": "string",
        "idUpload": "string",
        "ssn": "string",
        "driversLicenseNo": "string",
        "passportNumber": "string",
        "countryOfPassport": "string",
        "nationalId": "string",
        "lastErrorMessage": "string"
    }
}

ErrorParamResponse: object

success: boolean

Operation failed or not

message: string

Error or success message

data: object

Operation Result

Example
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}

RequireAuthResponse: object

success: boolean

Operation failed or not

message: string

Error or success message

data: object

Operation Result

Example
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}

AuthFailedResponse: object

success: boolean

Operation failed or not

message: string

Error or success message

data: object

Operation Result

Example
{
    "success": "boolean",
    "message": "string",
    "data": "object"
}