Paydentity

1 1. Introduction
2 2. Create API Request
3 3. API Request Response
4 4. ISX Transaction Page (how to receive notifications)
5 5. Returning to a Transaction
6 6. Results Page

1. Introduction

Paydentity is the first step in the sequence that enables a user to go through authentication and make a payment.

If you are implementing Identity Services, the transaction requires additional information from the cardholder.

Example: residential address, once obtained then 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.
ISX Transaction page.
Results page.

2. Create API Request

The request API consists of four steps: Method, URL, Header, and Body.

Request Method: POST

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/”.

Production Environment URL: https://gateway.isignthis.com/v1/authorization/

Required Headers

Complete the appropriate header information.

The API Header information is provided by the ISX relationship management team.

Field Name	Field Value

Field Name	Field Value
From	API client name
Authorization	Bearer API token
Content-Type	application/json

Example:

Field Name	Field Value

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.

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 each object name, object description, and whether an object is required or not is listed.

Also, the glossary column has a link that directs to detailed information about each object, including examples.

Object Name	Description	Required	Glossary

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

In the API body request, you need to replace the “workflow” name provided and replace “id” in the “merchant” object with the ones provided by the ISX relationship management team.

“Test_Workflow” text (in red below) must be replaced with the “workflow” name provided by the ISX relationship management team.

"workflow":"Test_Workflow"

“Test_Merchant” text (in red below) must be replaced with the “merchant_id” provided by the ISX relationship management team.

"id":"Test_Merchant"

The API call consists of the following 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

Sample JSON Body for Paydentity:

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

3. API Request Response

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

Field	Type	Description

Field	Type	Description
id/uid/context_uid	String	Unique response identification code. (Note: id/uid/context_uid, contain the same response code).
secret	String	The transaction secret code that can be used to validate ISX notifications.
mode	String	The transaction mode detected by ISX.
original_message	Object	Information about your transaction request.
state	String	Information about the state of the transaction.
compound_state	String	The ISX meaningful state of the transaction.
redirect_url	String	The redirect URL.

If successful, the response will have the following format:

Sample JSON Payment Response:

Opening the redirect_url on line 17 will display the transaction page

4. ISX Transaction Page (how to receive notifications)

Once the ISX transaction page is opened, the customer maybe prompted to insert additional information (depending on the settings that was requested), once completed you can proceed with the transaction.

For each unsuccessful transaction a customer makes, an appropriate event notification will be provided to your webhook.

Refer to Notifications and Transaction Events & States for more information.

5. Returning to a Transaction

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.

The customer will be able to return to their transaction as long as none of the final events has been sent to your webhook.

To implement a cancel transaction button, follow the example in Actions.

6. Results Page

Depending on which page you have decided to show, either the ISX results page or your own page.

This will be displayed to the customer with the appropriate message.

Refer to Transaction Events & States for more information.

If any issues arise, contact the ISX relationship management team.