API Glossary

For API operations, three fields are required for the header of the API POST.

Field	Type	ReferenceFW: Possible bug – Task review email link
profile	“Object”	KYC profile information. Profile Object
supporting_documents	“Array”	KYC supporting documents. Supporting Documents Object
id	“String”	The unique identifier for the identity, provided by iSignthis.

Field Name	Field Value
From	API client name
Authorization	Bearer API secret key
Content_type	Application/json

Note: From & Authorization Fields will be provided by iSignthis Merchant Support please contact them here.

Example:

Field Name	Field Value
From	Widgets-client.isignthis.com
Authorization	Bearer TEXnkvZCtFucXebHYwrYLIGbkhjygvBTbxWELCCnCQJTKsx6bYNh5fOjEE
Content_type	Application/json

All POST Objects present in API

Merchant Object

Field	Type	Required	Description	Example
id	“String”	Yes	Unique merchant identification code, provided by iSignthis.	`"m443100129408"`
return_url	“String”	No	This URL is where iSignthis will redirect the user after completing the transaction.	`"http://griffpetwholesa.le/completed?transaction_id="`

Sample JSON body merchant object

"merchant":{
    "id": "default",
    "return_url": "http://griffpetwholesa.le/completed?transaction_id="
}

Transaction Object

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

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

Sample JSON body transaction object

"transaction":{

    "id": "885e3506-eb13-4d2c-bc24-e336aaf94037",
    "datetime": "2015-11-30T23:48:49.701Z",
    "amount": "3100",
    "currency": "AUD",
    "init_recurring" : true,
    "reference": "their_transaction_reference"
}

Client Object

Field	Type	Required For:	Description	Example
ip	“String”	No	Internet protocol address of the client.	`"225.148.60.236"`
first_name	“String”	Yes	First name the client provided.	`"Shana"`
middle_name	“String”	No	Middle name the client provided.	`"Michelle"`
last_name	“String”	Yes	Last name the client provided.	`"Barrows"`
dob	“String”	Yes (Identity)	Date of birth, in YYYY-mm-dd format.	`"1981-10-01"`
gender	“String”	*Yes (Identity)	Gender of the client* (Required only for German eKYC)	`"male,female,other"`
email	“String”	Yes	Email address of the client.	`"shana.barrows@isignthis.com"`
mobile	“String”	Yes	E.123 international mobile phone number of the client.	`"+61434444444"`
phone_number	“String”	No	E.123 international home phone number of the client.	`"+61393677777"`
residential_address_secondary	“String”	No	Line 2 of the client’s residential address.	`"Room 1 Floor 5"`
residential_address_street	“String”	Yes (Identity)	Line 1 of the client’s residential address (without the street number).	`"Arthur Street"`
residential_address_street_number	“String”	Yes (Identity)	Street number of the client’s residential address.	`"42"`
residential_address_city	“String”	Yes (Identity)	City (Town/Locality) of the client’s residential address.	`"Ashfield"`
residential_address_postal_code	“String”	Yes (Identity)	Postal Code of the client’s residential address.	`"2131"`
residential_address_subdivision	“String”	*Yes (Identity)	ISO3166-2 State/County/Region/Province/Subdivision code of the client’s residential address. Do not prefix the country code.* (Required only for US, AU & CA eKYC).	`"NSW"`
residential_address_country	“String”	Yes (Identity)	ISO3166 country (alpha-2) of the client’s residential address.	`"AU"`
billing_address_secondary	“String”	No	Line 2 of the client’s billing address.	`"Room 1 Floor 5"`
billing_address_street	“String”	Yes (Payment Processing/Identity)	Line 1 of the client’s billing address (without the street number).	`"Arthur Street"`
billing_address_street_number	“String”	Yes (Identity) No (Payment Processing)	Street number of the client’s billing address.	`"42"`
billing_address_city	“String”	Yes (Payment Processing/Identity)	City (Town/Locality) of the client’s billing address.	`"Ashfield"`
billing_address_postal_code	“String”	Yes (Payment Processing/Identity)	Postal Code of the client’s billing address.	`"2131"`
billing_address_subdivision	“String”	No	ISO3166-2 State/County/Region/Province/Subdivision code of the client’s billing address. Do not prefix the country code.	`"NSW"`
billing_address_country	“String”	Yes (Payment Processing/Identity)	ISO3166 country (alpha-2) of the billing address.	`"AU"`
citizen_country	“String”	Yes (Identity)	ISO3166 citizen country (alpha-2) of the client.	`"AU"`
birth_country	“String”	No	ISO3166 birth country (alpha-2) of the client.	`"AU"`

Sample JSON body client object

"client" :{
    "first_name": "Shana",
    "last_name": "Barrows",
    "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",
    "email":"shana.barrows@isignthis.com",
    "mobile": "+61434444444"
}

Sample JSON body client object (Including optional fields)

"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	Example
pan	“String”	Yes	Primary account number, i.e., the “card number” on either a debit or a credit card.	`"4111117056800097"`
expiration_date	“String”	Yes	Four-digit representation of the PAN expiration date.	`"0618"`
cvv	“String”	Conditional	Card verification value	`"234"`
name	“String”	Yes	Name of primary account holder	`"Shana Barrows"`

Sample JSON body card holder object

"cardholder":{
    "pan": "4111117056800097",
    "expiration_date": "0618",
    "cvv": "234",
    "name": "Shana Barrows"
}

Payment Route Object

Field	Type	Required	Description	Example
acquirer_id	“String”	Yes	Force the payment route to go to specified ISX acquirer id and bypass ISX routing rules.	`"forceacquirierid"`

Sample JSON body payment route object

"payment_route":{
    "acquirer_id": "override-acquirer"
}

Account Object

Field	Type	Required	Description	Example
identifier_type	“String”	Yes	Reserved Field	”ID”
identifier	“String”	Yes	Merchant provided unique identifier for the end user account.	”2319383″
secret	“String”	No	The account secret code.	“083daa84-77b6-4817-a4f3-5771779c1c82″

Sample JSON body account object

"account":{
    "identifier_type": "ID",
    "identifier": "123456",
    "secret": "083daa84-77b6-4817-a4f3-5771779c1c82"
}

All GET objects

Card Reference Object

Field	Type	Description	Example
masked_pan	“String”	Primary account number masked, i.e. the “card number” on either a debit or a credit card.	`"411111....0097"`
card_brand	“String”	Card brand of the card number	`"VISA","MASTERCARD","AMERICAN_EXPRESS"`
expiry_date	“String”	Four-digit representation of the PAN expiration date.	`"0618"`
recurring_id	“String”	Referencing identifier for a completed transaction flaged as init-recurring, can be used to create/process subsequent recurring transactions.	`"f7fb955_15fc0a831d7__7fa7"`

Sample JSON card reference object

    {
        "masked_pan": "411111....0097",
        "card_brand": "VISA",
        "expiry_date": "1222",
        "recurring_id": "f7fb955_15fc0a831d7__7fa7"
    }

Original Message Object

Field	Type	Description	Example
merchant_id	“String”	Your merchant identification code, provided by iSignthis.	`"m443100129408"`
transaction_id	“String”	The request transaction identification code.	`"trx982319383v001"`
reference	“String”	Your transaction reference code.	`"ref98231-9383-001"`
account	Object	Information about the account.	Account object

Sample JSON body original message

{
    "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": {}
    }
}

Recurring Credential Object

Field	Type	Description	Example
recurring_id	“String”	Referencing identifier for a completed transaction flagged as init-recurring, provided by iSignthis.	`" _19477f08_15fc9c7_7f0b`“
status	“String”	The current status of the recurring credential.	`"ACTIVE"`
strength	“String”	The current strength of the recurring credential.	`"VALIDATED"`
origin_transaction_id	“String”	The id of the transaction flagged as init-recurring and originally activated the recurring series.	`"bb6361d3-4f34-4aaf-82d8-ae417ddf9f85"`
origin_merchant_id	“String”	Your merchant identification code.	`"3be27893_15afa290519_7c80"`
masked_pan	“String”	Primary account number masked, i.e. the “card number”, bound with the recurring series.	`"411111...1111"`
exp_date	“String”	Representation of the bound card number expiration date.	`"06-2018"`
recurring_type	“String”	The registered type of the recurring operation	`"authorization","credit"`
amount	“String”	The amount in the smallest currency unit (e.g. cents if using Euros) for the recurring transaction.	`"12545"`
currency	“String”	ISO4217 currency (alpha) code for the recurring transaction.	`"EUR"`
identifier	“String”	Merchant provided unique identifier (rid) for the end user account authorized for this recurring series.	`"unique_CRM_code"`
execution_counter	“String”	How many times the recurring operation was executed/processed successfully	`"7"`

Sample JSON body recurring credential

{
    "recurring_id": "_19477f08_15fc9c479c7__7f0b",
    "status": "ACTIVE",
    "strength": "VALIDATED",
    "origin_transaction_id": "bb6361d3-4f34-4aaf-82d8-ae417ddf9f85",
    "origin_merchant_id": "_3be27893_15afa290519__7c80",
    "masked_pan": "411111...1111",
    "exp_date": "12-2017",
    "recurring_type": "authorization",
    "amount": "12545",
    "currency": "EUR",
    "identifier": "unique_CRM_code",
    "execution_counter": "7"
}

Identity Object

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

Sample JSON body identity

{
    "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	Example
action	“String”	The action taken based on this PEP/Sanction result.	`"NO_ACTION"`
score	“String”	The average score of all attributes (Name, DOB, Address).	`"54"`
name_score	“String”	The score based on name.	`"100"`
dob_score	“String”	The score based on date of birth.	`"100"`
address_score	“String”	The score based on address.	`"-37"`
notes	“String”	A short description why the person is marked for screening as PEP/Sanction.	`"This is a mock result of a PEP/Sanction"`
listed_at	“String”	The time when the person was marked for screening.	`"2018-06-14"`
entity_formats	Object	The type of the screening (PEP and/or Sanction).	Entity Formats

Sample JSON body screen entities

{
    "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...",
        "listed": "2018-06-14",
        "entity_formats": {
        "SANCTIONS", "PEP"
        }
    }
}

Entity Formats Object

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

Sample JSON body entity formats

{
    "entity_formats":["OTHER", "PEP", "SANCTIONS"]
}

Outstanding Tasks Object

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

Sample JSON body outstanding tasks

{
    "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	Example
operation_type	“String”	The operation type.	`"authorization", "capture", "authorization-and-capture", "refund", "reverse", "credit"`
operation_successful	boolean	Indicates whether the operation was successful or not.	`true`
provider_type	“String”	The type of payment instrument.	`"credit_card"`
provider_name	“String”	The name of the Payment Provider.	`"ISXPay"`
request_currency	“String”	The ISO 4217 currency code of the requested currency.	`"EUR"`
reference_code	“String”	A unique identifier issued by iSignthis for this operation.	`"349351111111111111"`
provider_reference_code	“String”	The identifier issued by the payment provider for this operation.	`"1111111111"`
response_id	“String”	The response identifier.	`"jkw8vknj20fiyuhv3v"`
status_code	“String”	The status code returned from payment provider.	`"OK000"`
status_description	“String”	The status code description.	`"Success"`

Sample JSON body payment provider response

{
    "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	Example
currency	“String”	ISO4217 currency (alpha) code for payment.	“EUR”
amount	Number	The amount in the smallest currency unit (e.g. cents if using Euros).	3100

Sample JSON body payment amount

{
    "currency": "EUR",
    "amount": 3100
}

Profile Object

Field	Type	Description	Example
title	“String”	The client’s title.	`"Ms"`
first_name	“String”	The client’s first name.	`"Shana"`
middle_name	“String”	The client’s middle name(s).	`"Michelle"`
last_name	“String”	The client’s last name.	`"Barrows"`
fullname	“String”	The client’s full name.	`"Ms Shana Michelle Barrows"`
dob	“String”	The client’s date of birth, in YYYY-MM-DD format .	`"Ms"`
residential_address_secondary	“String”	Line 2 of the client’s residential address.	`"Room 1 Floor 5"`
residential_address_street	“String”	Line 1 of the client’s residential address (without the street number).	`"Arthur Street"`
residential_address_street_number	“String”	Street number of the client’s residential address.	`"42"`
residential_address_city	“String”	City (Town/Locality) of the client’s residential address.	`"Ashfield"`
residential_address_postal_code	“String”	Postal Code of the client’s residential address.	`"2131"`
residential_address_subdivision	“String”	Subdivision (State/Territory/Province) of the client’s residential address.	`"NSW"`
residential_address_country	“String”	ISO3166 country (alpha-2) of the client’s residential address.	`"AU"`
billing_address_secondary	“String”	Line 2 of the client’s billing address.	`"Room 1 Floor 5"`
billing_address_street	“String”	Line 1 of the client’s billing address (without the street number).	`"Arthur Street"`
billing_address_street_number	“String”	Street number of the client’s billing address.	`"42"`
billing_address_city	“String”	City (Town/Locality) of the client’s billing address.	`"Ashfield"`
billing_address_postal_code	“String”	Postal Code of the client’s billing address.	`"2131"`
billing_address_subdivision	“String”	Subdivision (State/Territory/Province) of the client’s billing address.	`"NSW"`
billing_address_country	“String”	ISO3166 country (alpha-2) of the billing address.	`"AU"`
citizen_country	“String”	ISO3166 citizen country (alpha-2) of the client.	`"AU"`
birth_country	“String”	ISO3166 birth country (alpha-2) of the client.	`"AU"`
email	“String”	Email address of the client.	`"shana.barrows@isignthis.com"`
mobile_number	“String”	E.123 international mobile phone number of the client.	`"+61434444444"`
phone_number	“String”	E.123 international phone number of the client.	`"+61393677777"`

Sample JSON body profile

{
    "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	Example
id	“String”	The unique identifier for the uploaded document.	`"6b90bfec_1588ab34f89__1b8d"`
mime_type	“String”	The document media type.	`"image/png", "image/jpeg", "application/pdf"`
bytes	Number	The document size in bytes.	`25124`
name	“String”	The original file name.	`"test.jpg", "bank_statement_jan.pdf"`
category	“String”	The document category.	`"GOVID", "STATEMENT"`
download_url	“String”	The URL you can use to download the file.	`"https://gateway.isignthis.com/v1/identity/document/59d83926-6d4c-4735-9858-97ccb6bb7316/6b90bfec_1588ab34f89__1b8d"`

Sample JSON body supporting documents

{
    "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	Example
match	“String”	The result of the electronic verification process. Can be ‘Match’ or ‘No match’.	`"NO_MATCH"`
details	“String”	All the databases the electronic verification process requested for a match. ‘0’ for no match or ‘1’ for match.	`""CREDIT_BUREAU_CONSUMER_NAME_ADDRESS": "1","TENANCY_DATABASE_NAME_DOB": "0"`

Sample JSON body external verification meta

{
    "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.

Sample JSON body error object

{
    "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.

Sample JSON body error details

{
    "id": "invalid-residential-address-country",
    "message": "Country code must be ISO 3166-1 Alpha 2"
}

HTTP Codes

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.

Search

Header