If you are implementing Identity services, more information from the cardholder is required to proceed with the payment.

The call is based on payment processing but requires additional end user data such as residential address, etc.

In our case the workflow of the payment processing consist the below four steps: Create API Request, Receive API Request Response, iSignthis Transaction page and Result page.

1. Create API  Request

The request API consists the below four steps: Method, URL, Header and Body

1.1. Method

Method used is POST.

1.2. URL

The API is accessed from the Request URL. This is a combination of your URL and the addition of the following text at the end of the URL: https://test.com/v1/authorization/”

1.3. Header

Fill in the appropriate header information. The API Header information is provided by the iSignthis Merchant Support team.

Field NameField Value
Fromapi client name
AuthorizationBearer API secret key
Content_typeapplication/json
Example:
Field NameField Value
FromTest_APIClient
AuthorizationBearer TEXnkvZCtFucXebHYwrYLIGbkhjygvBTbxWELCCnCQJTKsx6bYNh5fOjEE
Content_typeapplication/json

1.4. Body

In the API body request you need to add the  “workflow name” provided and replace “id” in the “merchant” object with the ones provided by merchant support.

Please look at the JSON code with the title “Sample JSON body for Payment Processing provided for reference.

“workflow”: “Test_Workflow” – “Test_Workflow” text should be replaced with the “workflow name” provided by iSignthis Merchant Support.

“merchant”: “id” : “Test_Merchant” – “Test_Merchant” text should be replaced with the “id” provided by iSignthis Merchant Support.

NOTE:In the “account” object –  identifier is the CUSTOMER ID THAT YOU ASSIGNED TO YOUR CUSTOMER. Each “identifier” must be unique and paired with the customer for future transactions.

The following API objects are required to generate the “Transaction API call”. Each object has a number of specific attributes in order to be successful.

Below you can view each object name, description and wether is required or not. Also, glossary column has a link that directs you to a more detailed information about each object including examples.

Object nameDescriptionRequiredGlossary
merchantInformation about the merchantYesMerchant object
transactionInformation about the transactionYesTransaction object
clientInformation about the clientYesClient Object
accountInformation about the accountYesAccount object
cardholderInformation on the cardholderNo*Cardholder object
Sample JSON body for Identity
{
    "workflow": "Test_Workflow",
    
    "merchant":  { 
           "id": "Test_Merchant"
        },
    "transaction": {
        "id": "Test_ID",
        "amount": "100",
        "currency": "AUD",
        "reference": "Test_Ref"
    },
    "client": {
        "first_name": "Shana",
        "last_name": "Barrows",
        "email":"shana.barrows@isignthis.com",
        "mobile": "+61434444444",
        "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": "Arthur Street",
        "billing_address_secondary": "PO Box 24",
        "billing_address_street_number": "42",
        "billing_address_city": "Ashfield",
        "billing_address_postal_code": "2131",
        "billing_address_subdivision": "NSW",
        "billing_address_country": "AU"

    },
    "account": {
        "identifier": "Test_ID"
    }
}

NOTE: *Cardholder object is only applicable if you have card numbers entered on your own payment page (Server to Server). You must be PCI certified to do this.

2.Receive API Request Response

Once the a POST is send a message will be received as a response. If successful it will have the following format.

If unsuccessful an error will be shown.

FieldTypeDescriptionExample
id“String”Unique response identification code.“e6988b4a-ed1c-4104-9caf-af6bb8769756”
secret“String”The transaction secret code that can be used to validate ISX notifications.“159173ee-6309-4806-b499-d2598a2ed21e”
mode“String”The transaction mode detected by iSignthis.“registration”
original_messageObjectInformation about your transaction request.Original Message Object
state“String”“PENDING
compound_state“String”The ISX meaningful state of the transaction“PENDING.VALIDATED_TRANSACTION”
redirect_url“String”The redirect URL“https://stage-verify.isignthis.com/vanilla/landing/e6988b4a-ed1c-4104-9caf-af6bb8769756”

Following the the redirect_url the transaction page will be displayed.

Sample JSON Payment Response:

{
    "id": "e6988b4a-ed1c-4104-9caf-af6bb8769756",
    "uid": "e6988b4a-ed1c-4104-9caf-af6bb8769756",
    "secret": "159173ee-6309-4806-b499-d2598a2ed21e",
    "context_uid": "e6988b4a-ed1c-4104-9caf-af6bb8769756",
    "mode": "registration",
   
    "original_message": {
        "merchant_id": "Test_Merchant",
        "transaction_id": "Test_ID",
        "reference": "Test_Ref"
    },
    "transactions": "[]",
    "state": "PENDING",
    "compound_state": "PENDING.VALIDATED_TRANSACTION",
    "redirect_url": "https://stage-verify.isignthis.com/vanilla/landing/e6988b4a-ed1c-4104-9caf-af6bb8769756"
 }

3. iSignthis Transaction page

The iSignthis transaction page is opened  , the customer will be  prompted to insert additional information, if any is required (depending on the settings that you requested) to proceed with the transaction.

For each unsuccessful try the customer makes, an appropriate event notification will be provided to your web hook.

Please check Notifications and events section for more information.

4. Results Page

Depending on which page  you have decided to show,  iSignthis results page or your own page will be displayed, to the customer with the according message.

Check events for more information.

If you have any issues don’t hesitate to contact our Merchant support team we will be happy to help.