API Glossary

Header

For API operations, 3 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`

The word Bearer must be present in the API token or else an error will result.

POST Objects

Merchant Object

Field	Type	Required	Description
`id`	String	Yes	Unique merchant ID code, provided by ISX.
`return_url`	String	No	This URL is where ISX will redirect a user after completing a transaction.
`transaction_webhook_url`	String	No	Using `transaction_webhook_url` field will override a default URL that was set with an ISX relationship management team 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 & 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	ISO 4217 currency (alphabetic) code (refer to this link for more info).
`reference`	String	Yes	Your transaction reference code.
`recurring_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 a client.
`first_name`	String	Yes	First name a client provided.
`middle_name`	String	No	Middle name a client provided.
`last_name`	String	Yes	Last name a client provided.
`dob`	String	Yes (Paydentity)	Date of birth Format: YYYY-mm-dd
`gender`	String	*Yes (Paydentity)	Gender of a client *(Required only for German eKYC)
`email`	String	Yes	Email address of a client.
`mobile`	String	Yes	International mobile phone number of a client. Format: E.123 Note: No spaces allowed.
`phone_number`	String	No	International home phone number of a client. Format: E.123 Note: No spaces allowed.
`residential_address_secondary`	String	No	Line 2 of a client’s residential address.
`residential_address_street`	String	Yes (Paydentity)	Line 1 of a client’s residential address (without a street number). Format: Only 24 characters allowed without special characters.
`residential_address_street_number`	String	Yes (Paydentity)	Street number of a client’s residential address.
`residential_address_city`	String	Yes (Paydentity)	City (Town/Locality) of a client’s residential address.
`residential_address_postal_code`	String	Yes (Paydentity)	Postal Code of a client’s residential address.
`residential_address_subdivision`	String	*Yes (Paydentity)	ISO 3166-2 State / County / Region / Province / Subdivision code of a 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-1 country (alpha-2) of a client’s residential address (refer to this link for more info).
`billing_address_secondary`	String	No	Line 2 of a client’s billing address.
`billing_address_street`	String	Yes	Line 1 of a client’s billing address (without a street number). Format: Only 24 characters allowed without special characters.
`billing_address_street_number`	String	No	Street number of a client’s billing address.
`billing_address_city`	String	Yes	City (Town/Locality) of a client’s billing address.
`billing_address_postal_code`	String	Yes	Postal Code of a client’s billing address.
`billing_address_subdivision`	String	No	ISO 3166-2 State / County / Region / Province / Subdivision code of a client’s billing address. Format: Do not prefix a country code.
`billing_address_country`	String	Yes	ISO 3166-1 country (alpha-2) of a billing address (refer to this link for more info).
`citizen_country`	String	Yes (Paydentity)	ISO 3166-1 citizen country (alpha-2) of a client (refer to this link for more info).
`birth_country`	String	No	ISO 3166-1 birth country (alpha-2) of a client (refer to this link for more info).

"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@mail.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@mail.com",

"mobile":"+61434444444",

"phone_number":"+61393677777"

}

Cardholder Object

Field	Type	Required	Description
`pan`	String	Yes	Primary account number, i.e., a “card number” on either a debit or a credit card.
`expiration_date`	String	Yes	4-digit representation of a 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 a 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 an end user account.
`secret`	String	No	A 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. a “card number” on either a debit or a credit card.
`card_brand`	String	Card brand of a card number.
`expiry_date`	String	4-digit representation of a 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	A request transaction identification code.
`reference`	String	Your transaction reference code.
`account`	Object	Info about an 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 a recurring credential.
`strength`	String	The current strength of a recurring credential.
`origin_transaction_id`	String	The id of a transaction flagged as init-recurring and originally activated a recurring series.
`origin_merchant_id`	String	Your merchant identification code.
`masked_pan`	String	Primary account number masked, i.e. a “card number”, bound with a recurring series.
`exp_date`	String	Representation of a bound card number expiration date.
`recurring_type`	String	The registered type of a recurring operation.
`amount`	String	The amount in a smallest currency unit (e.g., cents if using EUR) for a recurring transaction.
`currency`	String	ISO 4217 currency (alphabetic) code for a recurring transaction (refer to this link for more info).
`identifier`	String	Merchant provided unique identifier (rid) for an end user account authorised for this recurring series.
`execution_counter`	String	How many times a 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	a URL you can use to download a full PII info.
`ledger_lifetime_amount`	String	The total amount transacted by a client with a merchant in the smallest currency unit.
`ledger_lifetime_currency`	String	ISO 4217 currency (alphabetic) code for total transacted amount by a client with a merchant (refer to this link for more info).
`credit_ledger_lifetime_amount`	String	The total amount credited by a client with a merchant in the smallest currency unit.
`credit_ledger_lifetime_currency`	String	ISO 4217 currency (alphabetic) code for total credited amount by a client with a merchant (refer to this link for more info).
`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://api.isxpay.com/gateway/service/v1/authorization/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 or sanction result.
`screen_result`	Object	Contains a match rate of an 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 a person is marked for screening as PEP or 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 a 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 a task.
`type`	String	The type of an outstanding task.
`state`	String	The state of an 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 an outstanding task (Accept or 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 an operation was successful or not.
`provider_type`	String	The type of payment instrument.
`provider_name`	String	The name of a Payment Provider.
`request_currency`	String	ISO 4217 currency (alphabetic) code of a requested currency (refer to this link for more info).
`reference_code`	String	A unique reference code for a transaction.
`provider_reference_code`	String	The identifier issued by a 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 (alphabetic) code for payment (refer to this link for more info).
`amount`	Number	The amount in the smallest currency unit (e.g. cents if using EUR).

{

"currency":"EUR",

"amount":3100

}

Profile Object

Field	Type	Description
`title`	String	A client’s title.
`first_name`	String	A client’s first name.
`middle_name`	String	A client’s middle name(s).
`last_name`	String	A client’s last name.
`fullname`	String	A client’s full name.
`dob`	String	Format: YYYY-MM-DD.
`residential_address_secondary`	String	Line 2 of a client’s residential address.
`residential_address_street`	String	Line 1 of a client’s residential address (without a street number). Format: Only 24 characters allowed without special characters.
`residential_address_street_number`	String	Street number of a client’s residential address.
`residential_address_city`	String	City (Town/Locality) of a client’s residential address.
`residential_address_postal_code`	String	Postal Code of a client’s residential address.
`residential_address_subdivision`	String	Subdivision (State/Territory/Province) of a client’s residential address.
`residential_address_country`	String	ISO 3166-1 country (alpha-2) of a client’s residential address (refer to this link for more info).
`billing_address_secondary`	String	Line 2 of a client’s billing address.
`billing_address_street`	String	Line 1 of a client’s billing address (without a street number). Format: Only 24 characters allowed without special characters.
`billing_address_street_number`	String	Street number of a client’s billing address.
`billing_address_city`	String	City (Town/Locality) of a client’s billing address.
`billing_address_postal_code`	String	Postal Code of a client’s billing address.
`billing_address_subdivision`	String	Subdivision (State/Territory/Province) of a client’s billing address.
`billing_address_country`	String	ISO 3166-1 country (alpha-2) of a billing address (refer to this link for more info).
`citizen_country`	String	ISO 3166-1 citizen country (alpha-2) of a client (refer to this link for more info).
`birth_country`	String	ISO 3166-1 birth country (alpha-2) of a client (refer to this link for more info).
`email`	String	Email address of a client.
`mobile_number`	String	International mobile phone number of a client. Format: E.123 Note: No spaces allowed.
`phone_number`	String	International phone number of a 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@mail.com",

"mobile_number":"+61434444444",

"phone_number":"+61393677777"

}

Supporting Documents Object

Field	Type	Description
`id`	String	The unique identifier for an 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 that is used to download a file.

{

"id":"6b90bfec_1588ab34f89__1b8d",

"mime_type":"image/jpeg",

"bytes":25124,

"name":"test.jpg",

"category":"GOVID",

"download_url":"https://api.isxpay.com/gateway/service/v1/identity/

document/59d83926-6d4c-4735-9858-97ccb6bb7316/6b90bfec_1588ab34f89__1b8d"

}

External Verification Meta Object

Field	Type	Description
`match`	String	The result of an 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 a user can easily access, e.g., 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 a browser, this means the URL is not recognised. 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 that it does not know how to handle.

Mandate States

The mandate states are classified as follows:

State	Description
Cancelled	Mandate has been cancelled. Mandate cannot be triggered and/or edited.
Active	Mandate has been set up & active. Mandate can be edited and/or cancelled.
Declined	Mandate has been declined. Mandate cannot be triggered and/or edited.
Created	Mandate has been created, but pending activation. Mandate can be edited and/or cancelled.
Recorded	Mandate has been recorded on the database, but has not been processed yet.