Search

API Glossary

Header

Field Name Field Value
From API client name
Authorization Bearer API token
Content_type application/json

Example:

Field Name Field Value
From Test_APIClient
Authorization Bearer TEXnkvZCtFucXebHYwrYLIGbkhjygvBTbxWELCCnCQJTKsx6bYNh5fOjEE
Content_type application/json

POST Objects

Merchant Object

Field Type Required Description
id “String” Yes Unique merchant identification code, provided by ISX.
return_url “String” No This URL is where ISX will redirect the user after completing the transaction.
transaction_webhook_url “String” No Using “transaction_webhook_url” field will override the default URL that was set with Merchant support every time a request is sent. 
"merchant":{
    "id": "default",
    "return_url": "https://test/completed?transaction_id=",
    "transaction_webhook_url": "https://test.com/v1/notification"
   }

 

Transaction Object

Field Type Required Description  
id “String” Yes Your unique transaction identification code.  
datetime “String” No Date and time transaction has been recorded (javascript format).  
amount “String” Yes The transaction amount in the smallest currency unit (e.g. cents if using EUR).  
currency “String” Yes Transaction ISO 4217 currency (alpha) code.  
reference “String” Yes Your transaction reference code.
reccuring_id “String” No Your unique referencing identifier of a completed transaction flagged as init_recurring.
init_recurring boolean No To indicate the beginning/activation of a recurring series. 
"transaction": {
    "id": "885e3506-eb13-4d2c-bc24-e336aaf94037",
    "datetime": "2015-11-30T23:48:49.701Z",
    "amount": "3100",
    "currency": "AUD",
    "reference": "their_transaction_reference"
    "init_recurring": true
    "recurring_id": "f7fb955_15fc0a831d7__7fa7"
}

 

When recurring_id is provided, amount, currency and init_recurring should not be present in the request, or a validation error will occur.

Client Object

 

Field Type Required For: Description
ip String Yes Internet protocol address of the client.
first_name String Yes First name the client provided.
middle_name String No Middle name the client provided.
last_name String Yes Last name the client provided.
dob String        Yes 
(Paydentity)		 Date of birth
Format: YYYY-mm-dd 
gender String       *Yes 
(Paydentity)		 Gender of the client
*(Required only for German eKYC)
email String        Yes Email address of the client.
mobile String        Yes International mobile phone number of the client.
Format: E.123
Note: No spaces allowed. 
phone_number String        No International home phone number of the client.
Format: E.123
Note: No spaces allowed.
residential_address_secondary String        No Line 2 of the client’s residential address.
residential_address_street String       Yes 
(Paydentity)		 Line 1 of the client’s residential address 
(without the street number).
Note: no special characters
residential_address_street_number String       Yes 
(Paydentity)		 Street number of the client’s residential address.
residential_address_city String       Yes 
(Paydentity)		 City (Town/Locality) of the client’s residential address.
residential_address_postal_code String      Yes 
(Paydentity)		 Postal Code of the client’s residential address.
residential_address_subdivision String      *Yes 
(Paydentity)		 ISO 3166-2 State/County/Region/Province/Subdivision
code of the client’s residential address. 
* (Required only for US, AU & CA eKYC).
Format: Do not prefix the country code.
residential_address_country String        Yes
 (Paydentity)		 ISO 3166 country (alpha-2) of the client’s 
residential address.
billing_address_secondary String        No Line 2 of the client’s billing address.
billing_address_street String       Yes  Line 1 of the client’s billing address 
(without the street number).
Note: No special characters.
billing_address_street_number String       No Street number of the client’s billing address.
billing_address_city String       Yes City (Town/Locality) of the client’s billing address.
billing_address_postal_code String       Yes  Postal Code of the client’s billing address.
billing_address_subdivision String       No ISO 3166-2 State/County/Region/Province/Subdivision
code of the client’s billing address. 
Format: Do not prefix the country code.
billing_address_country String      Yes  ISO 3166 country (alpha-2) of the billing address.
citizen_country String      Yes
(Paydentity)		 ISO 3166 citizen country (alpha-2) of the client.
birth_country String      No ISO 3166 birth country (alpha-2) of the client. 
"client" :{
    "first_name": "Shana",
    "last_name": "Barrows",
    "billing_address_street" :"AU",
    "billing_address_street_number" : "42",
    "billing_address_secondary": "PO Box 24",
    "billing_address_city": "Ashfield",
    "billing_address_postal_code": "2131",
    "billing_address_subdivision": "NSW",
    "billing_address_country": "AU",
    "email":"shana.barrows@isignthis.com",
    "mobile": "+61434444444"
}

Sample JSON with all the optional code

"client" :{
    "ip": "225.148.60.236",
    "title": "Ms",
    "first_name": "Shana",
    "middle_name": "Michelle",
    "last_name": "Barrows",
    "dob": "1981-10-01",
    "gender": "female",
    "residential_address_street": "Arthur Street",
    "residential_address_secondary": "PO Box 24",
    "residential_address_street_number": "42",
    "residential_address_city": "Ashfield",
    "residential_address_postal_code": "2131",
    "residential_address_subdivision": "NSW",
    "residential_address_country": "AU",
    "billing_address_street":"AU",    
    "billing_address_secondary": "PO Box 24",
    "billing_address_city": "Ashfield",
    "billing_address_postal_code": "2131",
    "billing_address_subdivision": "NSW",
    "billing_address_country": "AU",
    "citizen_country": "AU",
    "birth_country": "AU",
    "email":"shana.barrows@isignthis.com",
    "mobile": "+61434444444",
    "phone_number": "+61393677777"
}

 

Cardholder Object

Field Type Required Description
pan “String” Yes Primary account number, i.e., the “card number” on either a debit or a credit card.
expiration_date “String” Yes Four-digit representation of the PAN expiration date.
cvv “String” Conditional Card verification value.
name “String” Yes Name of primary account holder. 
"cardholder":{
    "pan": "4111117056800097",
    "expiration_date": "0618",
    "cvv": "234",
    "name": "Shana Barrows"
}

 

Payment Route Object

Field Type Required Description
acquirer_id “String” No Force the payment route to go to specified ISX acquirer id and bypass ISX routing rules. 
"payment_route":{
    "acquirer_id": "override-acquirer"
}

 

Account Object

Field Type Required Description
identifier “String” Yes Merchant provided unique identifier for the end user account.
secret “String” No The account secret code. 
"account":{ 
"identifier": "123456", 
"secret": "083daa84-77b6-4817-a4f3-5771779c1c82"
}
 

Get Objects

Card Reference Object

Field Type Description
masked_pan “String” Primary account number masked, i.e. the “card number” on either a debit or a credit card.
card_brand “String” Card brand of the card number.
expiry_date “String” Four-digit representation of the PAN expiration date. 
"account":{
        "masked_pan": "411111....0097",
        "card_brand": "VISA",
        "expiry_date": "1222"
}

 

Original Message Object

Field Type Description
merchant_id “String” Your merchant identification code, provided by ISX.
transaction_id “String” The request transaction identification code.
reference “String” Your transaction reference code.
account Object Information about the account. 
{
    "merchant_id": "default",
    "transaction_id": "their_transaction_id",
    "reference": "their_transaction_reference",
    "account": {
        "identifier_type": "ID",
        "identifier": "unique_CRM_code",
        "secret": "SOLLIP",
        "full_name": "Firstname Lastname"
    }
}

 

Recurring Credential Object

Field Type Description
recurring_id “String” Referencing identifier for a completed transaction flagged as init-recurring, provided by ISX.
status “String” The current status of the recurring credential.
strength “String” The current strength of the recurring credential.
origin_transaction_id “String” The id of the transaction flagged as init-recurring and originally activated the recurring series.
origin_merchant_id “String” Your merchant identification code.
masked_pan “String” Primary account number masked, i.e. the “card number”, bound with the recurring series.
exp_date “String” Representation of the bound card number expiration date.
recurring_type “String” The registered type of the recurring operation
amount “String” The amount in the smallest currency unit (e.g. cents if using Euros) for the recurring transaction.
currency “String” ISO 4217 currency (alpha) code for the recurring transaction.
identifier “String” Merchant provided unique identifier (rid) for the end user account authorised for this recurring series.
execution_counter “String” How many times the recurring operation was executed/processed successfully. 
{
    "merchant_id": "default",
    "transaction_id": "their_transaction_id",
    "reference": "their_transaction_reference",
    "account": {
        "identifier_type": "ID",
        "identifier": "unique_CRM_code",
        "secret": "SOLLIP",
        "full_name": "Firstname Lastname",
        "ext": {}
    }
}
 

Identity Object

Field Type Description
id “String” Client’s identity unique id, provided by ISX.
download_url “String” The URL you can use to download the full PII information.  
ledger_lifetime_amount “String” The total amount transacted by the client with the merchant in the smallest currency unit.
ledger_lifetime_currency “String” ISO 4217 currency (alpha) code for total transacted amount by the client with the merchant.
credit_ledger_lifetime_amount “String” The total amount credited by the client with the merchant in the smallest currency unit.
credit_ledger_lifetime_currency “String” ISO 4217 currency (alpha) code for total credited amount by the client with the merchant.
kyc_state “String” The KYC State (NONE, NEW, HOLD, ACCEPTED, REJECTED, EXPIRED).
created_at “String” The time this identity was created (javascript format). 
{
    "id": "_b103fc0_158a2f3a950__7e12",
    "download_url": "https://gateway.isignthis.com/v1/identity/_b103fc0_158a2f3a950__7e12",
    "ledger_lifetime_amount": "63828",
    "ledger_lifetime_currency": "EUR",
    "credit_ledger_lifetime_amount": "14625",
    "credit_ledger_lifetime_currency": "EUR",
    "kyc_state": "NONE",
    "created_at": "2016-11-26T23:34:51.301Z"
}

 

Screen Entities Object

Field Type Description
action “String” The action taken based on this PEP/Sanction result.
Screen_result “Object” Contains the match rate of the individual.
score “String” The average score of all attributes (Name, DOB, Address).
name_score “String” The score based on name.
dob_score “String” The score based on date of birth.
address_score “String” The score based on address.
address “String” The billing address.
notes “String” A short description why the person is marked for screening as PEP/Sanction. 
{
    "action": "NO_ACTION",
    "screen_result": {
        "score": "15",
        "name_score": "78",
        "dob_score": "23",
        "address_score": "100",
        "address": "12 Address 1234 Melbourne Australia",
        "notes":"This is a PEP/Sanction Result because...",
    }
}

 

Entity Formats Object

Field Type Description
entity_formats “String” The genre of the screening (PEP and/or Sanction). May include multiple selections. 
{
    "entity_formats":["OTHER", "PEP", "SANCTIONS"]
}

Outstanding Task Object

Field Type Description
id “String” The ID of the task.
type “String” The type of the outstanding task.
state “String” The state of the outstanding task.
awaiting “String” The task awaits action from an operator.
created_at “String” The time this identity was created.
available_actions “String” The available actions for the outstanding task (Accept/Reject). 
{
    "id": "94a2a6d_1640152fd0b_271x",
    "type": "KYC_MANUAL_REVIEW",
    "state": "NEW",
    "awaiting": "OPERATOR",
    "created_at": "2018-06-15T09:07:43.031Z",
    "updated_at": "2018-06-15T09:07:43.031Z",
    "available_actions": [
        "accept",
        "reject"]
}
 

Payment Provider Response Object

Field Type Description
operation_type “String” The operation type.
operation_successful boolean Indicates whether the operation was successful or not.
provider_type “String” The type of payment instrument.
provider_name “String” The name of the Payment Provider.
request_currency “String” The ISO 4217 currency code of the requested currency.
reference_code “String” A unique reference code for the transaction.
provider_reference_code “String” The identifier issued by the payment provider for this operation.
response_id “String” The response identifier.
status_code “String” The status code returned from payment provider.
status_description “String” The status code description. 
{
    "operation_type": "authorization-and-capture",
    "operation_successful": true,
    "provider_type": "credit_card",
    "provider_name": "ISXPay",
    "request_currency": "EUR",
    "reference_code": "349351111111111111",
    "provider_reference_code": "1111111111",
    "response_id": "jkw8vknj20fiyuhv3v",
    "status_code": "OK000",
    "status_description": "Success"
}
 

Payment Amount Object

Field Type Description
currency “String” ISO 4217 currency (alpha) code for payment.
amount Number The amount in the smallest currency unit (e.g. cents if using Euros). 
{
    "currency": "EUR",
    "amount": 3100
}
 

Profile Object

Field Type Description
title “String” The client’s title.
first_name “String” The client’s first name.
middle_name “String” The client’s middle name(s).
last_name “String” The client’s last name.
fullname “String” The client’s full name.
dob “String”

Format: YYYY-MM-DD.
residential_address_secondary “String” Line 2 of the client’s residential address.
residential_address_street “String” Line 1 of the client’s residential address (without the street number).
Format: Only 24 characters allowed without special characters.
residential_address_street_number “String” Street number of the client’s residential address.
residential_address_city “String” City (Town/Locality) of the client’s residential address.
residential_address_postal_code “String” Postal Code of the client’s residential address.
residential_address_subdivision “String” Subdivision (State/Territory/Province) of the client’s residential address.
residential_address_country “String” ISO 3166 country (alpha-2) of the client’s residential address.
billing_address_secondary “String” Line 2 of the client’s billing address.
billing_address_street “String” Line 1 of the client’s billing address (without the street number).
Format: Only 24 characters allowed without special characters.
billing_address_street_number “String” Street number of the client’s billing address.
billing_address_city “String” City (Town/Locality) of the client’s billing address.
billing_address_postal_code “String” Postal Code of the client’s billing address.
billing_address_subdivision “String” Subdivision (State/Territory/Province) of the client’s billing address.
billing_address_country “String” ISO 3166 country (alpha-2) of the billing address.
citizen_country “String” ISO 3166 citizen country (alpha-2) of the client.
birth_country “String” ISO 3166 birth country (alpha-2) of the client.
email “String” Email address of the client.
mobile_number “String” International mobile phone number of the client.
Format: E.123
Note: No spaces allowed.
phone_number “String” International phone number of the client.
Format: E.123
Note: No spaces allowed.		 
{
    "title": "Ms",
    "first_name": "Shana",
    "middle_name": "Michelle",
    "last_name": "Barrows",
    "fullname": "Ms Shana Michelle Barrows",
    "dob": "1981-10-01",
    "residential_address_secondary": "Unit 1",
    "residential_address_street": "Arthur Street",
    "residential_address_street_number": "42",
    "residential_address_city": "Ashfield",
    "residential_address_postal_code": "2131",
    "residential_address_subdivision": "NSW",
    "residential_address_country": "AU",
    "billing_address_secondary": "PO Box 24",
    "billing_address_city": "Ashfield",
    "billing_address_postal_code": "2131",
    "billing_address_subdivision": "NSW",
    "billing_address_country": "AU",
    "citizen_country": "AU",
    "birth_country": "AU",
    "email":"shana.barrows@isignthis.com",
    "mobile_number": "+61434444444",
    "phone_number": "+61393677777"
}
 

Supporting Documents Object

Field Type Description
id “String” The unique identifier for the uploaded document.
mime_type “String” The document media type.
bytes Number The document size in bytes.
name “String” The original file name.
category “String” The document category.
download_url “String” The URL you can use to download the file. 
{
    "id": "6b90bfec_1588ab34f89__1b8d",
    "mime_type": "image/jpeg",
    "bytes": 25124,
    "name": "test.jpg",
    "category": "GOVID",
    "download_url": "https://gateway.isignthis.com/v1/identity/document/59d83926-6d4c-4735-9858-97ccb6bb7316/6b90bfec_1588ab34f89__1b8d"
}
 

External Verification Meta Object

Field Type Description
match “String” The result of the electronic verification process. Can be ‘Match’ or ‘No match’.
details “Object” All the databases the electronic verification process requested for a match. ‘0’ for no match or ‘1’ for match. 
{
    "match": "NO_MATCH",
    "detail": {
        "CREDIT_BUREAU_CONSUMER_NAME_ADDRESS": "0",
        "TENANCY_DATABASE_NAME_DOB": "0",
        "TENANCY_DATABASE_NAME_ADDRESS": "0",
        "HISTORICAL_ELECTORAL_NAME_ADDRESS": "0",
        "CREDIT_BUREAU_PUBLIC_RECORD_NAME_DOB": "0",
        "CREDIT_BUREAU_COMMERCIAL_NAME_DOB": "0",
        "CREDIT_BUREAU_CONSUMER_NAME_DOB": "0",
        "CREDIT_BUREAU_PUBLIC_RECORD_NAME_ADDRESS_DOB": "0",
        "CREDIT_BUREAU_CONSUMER_NAME_ADDRESS_DOB": "0",
        "PROPRIETARY_TELEPHONE_DIRECTORY_NAME_ADDRESS": "0",
        "ELECTORAL_NAME_ADDRESS": "0",
        "CREDIT_BUREAU_COMMERCIAL_NAME_ADDRESS_DOB": "0",
        "CREDIT_BUREAU_PUBLIC_RECORD_NAME_ADDRESS": "0",
        "CREDIT_BUREAU_COMMERCIAL_NAME_ADDRESS": "0",
        "TELEPHONE_DIRECTORY_NAME_ADDRESS": "0",
        "TENANCY_DATABASE_NAME_ADDRESS_DOB": "0",
        "NAME_DOB_PASSPORT": "0"
        }
}
 

Error Object

Field Type Description
code “String” The error code.
message “String” A description of the error.
details “Array” Details for validation errors. 
{
    "code": "VALIDATION_ERROR",
    "message": "Your request failed validation. Please check your parameters satisfies requirements specified in the API documentation.",
    "details": [
        {
            "id": "invalid-dob",
            "message": "A valid date of birth must be used (yyyy-mm-dd)"
        },
        {
            "id": "invalid-transaction-currency",
            "message": "Transaction currency must be ISO 4217"
        },
        {
            "id": "invalid-residential-address-country",
            "message": "Country code must be ISO 3166-1 Alpha 2"
        }
    ]
}
 

Error Details Object

Field Type Description
id “String” The error detail id.
message “String” A description of the error detail.  
{
    "id": "invalid-residential-address-country",
    "message": "Country code must be ISO 3166-1 Alpha 2"
}
 

Workflow State Object

Field Type Description
capture “String” Capture is not applicable.
charge “String” Charge process has been accepted.
credit “String” Credit is not applicable.
3ds “String” 3ds is not applicable.
piv “String” Piv is not applicable.
sca “String” Sca has been skipped.
docs “String” Docs is not applicable.
kyc “String” Kyc verification has been accepted. 
"workflow_state": {
        "capture": "NA",
        "charge": "ACCEPTED",
        "credit": "NA",
        "3ds": "NA",
        "piv": "NA",
        "sca": "SKIPPED",
        "docs": "NA",
        "kyc": "ACCEPTED"
    }
 

HTTP Codes

The Hypertext Transfer Protocol (HTTP) is an application layer protocol in the Internet protocol suite model for distributed, collaborative, hypermedia information systems. HTTP is the foundation of data communication for the World Wide Web, where hypertext documents include hyperlinks to other resources that the user can easily access, for example, by a mouse click or by tapping the screen in a web browser.

The API returns standard HTTP success or error status codes.

HTTP status codes are classified as follows:

Code range Description
100 – 199 Informational responses
200 – 299 Successful responses
300 – 399 Redirection messages
400 – 499 Client error messages
500 – 599 Server error messages

The various HTTP status codes that might be returned are listed below:

Code Name Description
201 OK The request succeeded, and a new resource was created as a result. The transaction was successfully created.
400 Bad Request The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). The request failed, as the transaction is its final state.
401 Unauthorized Although the HTTP standard specifies “unauthorized”, semantically this response means “unauthenticated”. That is, the client must authenticate itself to get the requested response. The request failed authentication.
404 Not Found The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. The transaction does not exist.
500 Internal Server Error There was a server side error. The server has encountered a situation it does not know how to handle.

© 2013-2023 ISX Financial . All rights reserved.