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 iSignthis.
return_url “String” No This URL is where iSignthis 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 Euros).  
currency “String” Yes Transaction ISO4217 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).
Format: Only 24 characters allowed 
without 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)		 ISO3166-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)		 ISO3166 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).
Format: Only 24 characters allowed 
without 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 ISO3166-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  ISO3166 country (alpha-2) of the billing address.
citizen_country String      Yes
(Paydentity)		 ISO3166 citizen country (alpha-2) of the client.
birth_country String      No ISO3166 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 iSignthis.
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 iSignthis.
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” ISO4217 currency (alpha) code for the recurring transaction.
identifier “String” Merchant provided unique identifier (rid) for the end user account authorized 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 iSignthis.
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” ISO4217 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” ISO4217 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 identifier issued by iSignthis for this operation.
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” ISO4217 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” ISO3166 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” ISO3166 country (alpha-2) of the billing address.
citizen_country “String” ISO3166 citizen country (alpha-2) of the client.
birth_country “String” ISO3166 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

API returns standard HTTP success or error status codes.

The various HTTP status codes we might return are listed below:

Code Description
201 The transaction was successfully created.
400 The request failed, as the transaction is its final state.
401 The request failed authentication.
404 The transaction does not exist.
500 There was a server side error.

© 2013-2020 iSignthis Ltd (ASX: ISX | FRA: TA8). All rights reserved.