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

FieldTypeReferenceFW: 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 NameField Value
FromAPI client name
AuthorizationBearer API secret key
Content_typeApplication/json

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

Example:

Field NameField Value
FromWidgets-client.isignthis.com
AuthorizationBearer TEXnkvZCtFucXebHYwrYLIGbkhjygvBTbxWELCCnCQJTKsx6bYNh5fOjEE
Content_typeApplication/json

All POST Objects present in API

Merchant Object

FieldTypeRequiredDescriptionExample
id“String”YesUnique merchant identification code, provided by iSignthis."m443100129408"
return_url“String”NoThis 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

FieldTypeRequiredDescriptionExample
id“String”YesYour unique transaction identification code."885e3506-eb13-4d2c-bc24-e336aaf94037"
recurring_id“String”NoYour unique referencing identifier of a completed transaction flagged as init_recurring."f7fb955_15fc0a831d7__7fa7"
datetime“String”NoDate and time transaction has been recorded (javascript format)."2015-11-30T23:48:49.701Z"
amount“String”YesThe transaction amount in the smallest currency unit (e.g. cents if using Euros). Invalid if"1800"
currency“String”YesTransaction ISO4217 currency (alpha) code."AUD"
init_recurringbooleanNoTo indicate the beginning/activation of a recurring series.true,false
reference“String”YesYour 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

FieldTypeRequired For:DescriptionExample
ip“String”NoInternet protocol address of the client."225.148.60.236"
first_name“String”YesFirst name the client provided."Shana"
middle_name“String”NoMiddle name the client provided."Michelle"
last_name“String”YesLast 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”YesEmail address of the client."shana.barrows@isignthis.com"
mobile“String”YesE.123 international mobile phone number of the client."+61434444444"
phone_number“String”NoE.123 international home phone number of the client."+61393677777"
residential_address_secondary“String”NoLine 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”NoLine 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”NoISO3166-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”NoISO3166 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

FieldTypeRequiredDescriptionExample
pan“String”YesPrimary account number, i.e., the “card number” on either a debit or a credit card."4111117056800097"
expiration_date“String”YesFour-digit representation of the PAN expiration date."0618"
cvv“String”ConditionalCard verification value"234"
name“String”YesName 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

FieldTypeRequiredDescriptionExample
acquirer_id“String”YesForce 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

FieldTypeRequiredDescriptionExample
identifier_type“String”YesReserved Field”ID”
identifier“String”YesMerchant provided unique identifier for the end user account.”2319383″
secret“String”NoThe 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

FieldTypeDescriptionExample
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

FieldTypeDescriptionExample
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"
accountObjectInformation 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

FieldTypeDescriptionExample
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

FieldTypeDescriptionExample
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

FieldTypeDescriptionExample
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_formatsObjectThe 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

FieldTypeDescriptionExample
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

FieldTypeDescriptionExample
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

FieldTypeDescriptionExample
operation_type“String”The operation type."authorization", "capture", "authorization-and-capture", "refund", "reverse", "credit"
operation_successfulbooleanIndicates 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

FieldTypeDescriptionExample
currency“String”ISO4217 currency (alpha) code for payment.“EUR”
amountNumberThe amount in the smallest currency unit (e.g. cents if using Euros).3100

Sample JSON body payment amount

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

Profile Object

FieldTypeDescriptionExample
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

FieldTypeDescriptionExample
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"
bytesNumberThe 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

FieldTypeDescriptionExample
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

FieldTypeDescription
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

FieldTypeDescription
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

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