Paydentity is the first step of the sequence, that enable the users to go through authentication and make a payment. 

If you are implementing Identity Services, the call requires additional information of the end user from the cardholder such as residential address to proceed with the payment.

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

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

1.1. Method

Request Method: POST.

1.2. URL

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

URL For Stage Environment:

https://stage-gateway.isignthis.com/v1/authorization/

URL For Production Environment:

https://gateway.isignthis.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 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

1.4. Body

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

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

Object name Description Required Glossary
merchant Information of the merchant Yes Merchant object
transaction Information of the transaction Yes Transaction object
client Information of the client Yes Client Object
account Information of the account Yes Account object
cardholder Information of the cardholder No* Cardholder object

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.

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.

Test_Workflow” text should be replaced with the “workflow name” provided by iSignthis Merchant support team.

 

“workflow”:“Test_Workflow”

Test_Merchant” text should be replaced with the “merchant_id” provided by iSignthis Merchant support team.

“id”:“Test_Merchant”

 

The API call consists of required fields to proceed with the payment:

– first_name

– last_name

– dob

– gender

– email

– mobile

– billing_address_street

– billing_address_street_number (optional)

– billing_address_city

– billing_address_postal_code

– billing_address_country

– residential_address_street

– residential_address_street_number 

– residential_address_city

– residential_address_postal_code

– residential_address_subdivision (US,AU,CA)

– residential_address_country

– citizen_country

 

 Please look at the JSON code with the title “Sample JSON body for Paydentity” provided for reference.

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.

 

Sample JSON body for Acquiring:

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

Once the POST is sent, a message will be received as a response. 

Field Type Description Example
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_message Object Information about your transaction request. Original Message Object
state “String” Information about the state of the transaction "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"

If successful it will have the following format:

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"

}

Opening the redirect_url will display the transaction page

NOTEIf the API request response is unsuccessful an error will be shown.

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 Transaction events section for more information.

Returning to a transaction is an important factor when conducting a Paydentity workflow. A customer might not have on hand the documents which are required to complete a KYC process and therefore return later to the transaction when all documents have been gathered.

For a customer to be able to return to a transaction and complete the KYC process, the redirect url from the API Request Response must be stored by the merchant and be accessible by the customer later on.

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 Transaction events and Transaction states for more information.

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