Card Payments

1 1. Introduction
2 2. Create API Request
3 3. Receive API Request Response
4 4. ISX Transaction Page (how to receive notifications)
5 5. Results Page
6 6. Acquiring Notifications
7 7. Test Card CVV’s

1. Introduction

Acquiring, is the first step of the sequence, that enables the user to go through authentication and make a payment.

Different information can be included in the API request, however there are some specific objects that are required for a successful authentication process.

The API call requires information about the billing address to proceed with the payment.

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

If you are doing Sofort or POLi integration, follow the same acquiring procedure.

2. Create API Request

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

Request Method: POST

The API is accessed from the Request URL.

Environments:

Production API URL: https://gateway.isignthis.com/v1/authorization/
Stage API URL: https://stage-gateway.isignth.is/v1/authorization/

Fill in 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
Authentication	Bearer API token
Content-Type	application/json

Example:

Field Name	Field Value

Field Name	Field Value
From	Test_APIClient
Authentication	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.

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
cardholder	Information of the cardholder	No*	Cardholder Object

*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.
ISX will need to review and approve the PCI documents in order to allow server to server integrations.

“Test_Workflow” text must be replaced with the “workflow name” provided by the ISX relationship management team.

"workflow":"Test_Workflow"

“Test_Merchant” text must be replaced with the “merchant_id” provided by the ISX relationship management team.

"id":"Test_Merchant"

The API call also consists of the following required fields that you need to complete to proceed with the payment:

first_name
last_name
email
mobile
billing_address_street
billing_address_street_number
billing_address_city
billing_address_postal_code
billing_address_country

Refer to the JSON code on the left-hand side provided for reference.

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",
		"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. Receive API Request Response

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

Field	Type	Description

Field	Type	Description
id/uid	String	Unique response identification 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.

Sample JSON Payment Response

Following the redirect_url, will lead to 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 requested), once completed, 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 for more information.

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

In case of any issues, contact the ISX relationship management team.

6. Acquiring Notifications

Below are various acquiring notifications (to view an example of an entire JSON payment response, refer to the above sample payment, section 2).

Transaction Start

The initial notification will be the transaction_start notification.

JSON Extract

Transaction Pending

If or when an authorization is made on the customer’s card

JSON Extract

Payment Accepted

If or when funds are captured/debited from the customer’s card (this is not the final notification, in case you initiate a refund to the customer, receive a fraud or a chargeback notification for the relevant transaction).

JSON Extract

Refunds

In case of a refund (full or partial refund) being initiated from your side, you will receive the following notifications:

Refunds Pending

When a transaction is in the process of being refunded.

JSON Extract

Refund Issued

When a (partial or full) refund is completed successfully.

JSON Extract

Final Notifications

The final notifications (events) which are relevant to you, are the following:

JSON Extract

7. Test Card CVV’s

As part of our integration process, we will provide you with a test card.

Note the CVV codes in the table below.

Depending on the results of your tests, you will notice different notifications being sent.

If you wish, you can update your CRM system according to the transaction notifications.

CVV From (inclusive)	CVV To (inclusive)	Transaction Result

CVV From (inclusive)	CVV To (inclusive)	Transaction Result
001	199	OK (Success)
200	299	Incorrect CVV
300	399	Invalid Currency
400	499	Insufficient Funds
500	599	Card Lost
600	699	Card Restricted
700	799	Declined (by Issuer)
800	899	Suspected Fraud
900	999	General Error