API Glossary
- Home
- API Glossary
Header
For API operations, three fields are required for the header of the API POST.
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) |
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 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” | 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. |
“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. |