Key Concepts

Key Concepts in the API

The API allows you to manage various aspects of your payment system, such as customers, payment instruments, transactions, and reporting. Here is a brief explanation of the key concepts and how they work.

Customers

A customer is a way of storing the information of an individual or business entity that you want to charge in the future. You can create a customer token with the API, which will have a unique Id and some basic details, such as name, email address, and your own reference. A customer token can have one or more payment instruments associated with it.

Payment Instruments

A payment instrument is a tokenized payment method, such as a card, bank account, wallet, or payment agreement. Payment instruments can be created as standalone resources or attached to a customer, depending on how you want to manage reuse and lookup in your integration.

Fingerprinting

When creating a payment instrument, the API generates a fingerprint from the underlying card or bank account details. The fingerprint will be returned as metadata in the response. And multiple payment instruments may share the same fingerprint identifier when they represent the same underlying payment details. To enforce duplicate protection, include the If-None-Match: * header when creating a payment instrument. When If-None-Match: * is provided and a duplicate is found, the API returns 412 Precondition Failed and does not create a new payment instrument. When If-None-Match: * is not provided but a duplicate is found, the request can proceed and returns the existing fingerprint identifier.

Customers and Payment Instruments Relationship

A customer can have one or many payment instruments, but payment instruments can also exist as standalone records without attaching to a customer. When a payment instrument is attached to a customer, the customer fields are populated. When it is standalone, the customer fields are empty. Payment instruments can be attached to or detached from a customer at any time.

Transactions

A transaction is the exchange of money between a payer and a payee. A transaction will have an Id and some properties, such as amount, status, reference, etc. The status will indicate whether the transaction is successful, declined or still processing. As these transactions may require raw card data to be passed through your systems, there may be additional technical considerations to ensure that your environment is handling the card data in a PCI-DSS compliant manner.

There are six types of transactions supported in the API.

• Purchase: This is a standard ecom transaction that will submit a payment request to the payment network.
• PreAuthorisation: This is used to reserve funds that will later be captured as a partial or full amount. eg. A hotel reserving a security deposit on your card at the beginning of your stay.
• Capture: This is used to capture the funds previously reserved by a PreAuthorisation request.
• Void: This is used to cancel a PreAuthorisation prior to the funds being captured. This will release the funds back to the cardholder.
• Refund: This is used to refund a successful payment. A refund can only be processed against a completed payment.
• 3D Secure 2.0: This method allows you to verify the cardholder using 3D Secure 2.0 before you process their Purchase or PreAuthorisation transaction.

Reporting

Reporting is a feature that allows you to generate a summary of your transactions for a given period of time. You can use the API to create two kinds of reports:

• Transaction Report: This report will list all the transactions that were processed within a certain time range.
• Settlement Report: This report will show all the transactions and fees that were settled within a certain time range.

Querying

Querying is a function that allows you to filter and search for specific resources based on some criteria. Since a query can return many results depending on your filters, the API uses paging to ensure a fast response.

Ids in the API

Ids are commonly used throughout our API to provide you with a unique identifier to later reference the resource or process.

Below are the two common types of Ids you will encounter in the API.

Resource Id

The Resource Id is the unique identifier of each resource created as part of the API request. It has a max length of 30 characters.
eg. E1HKfn68Pkms5zsZsvKONwNw

When used under the resource identifies, it will simply be referred to as id, however when referenced under another resource it will be formatted as resourceId.
eg. paymentInstrumentId

Correlation Id

The Correlation Id is a unique identifier assigned to each API request. It will be present in the x-correlation-id field in the header of each response. This will be formatted as a UUID or GUID.
eg. 57b38524-630c-4832-909d-bb8a8cee8815

As the Correlation Id is a unique identifier for a process in the API, it can be useful for helping support staff diagnose an issue, especially in the event where a system error occurs and a Resource Id is not created.

Reference

The Reference is your own unique identifier that you can provide when creating a resource or transaction. When left blank, a reference will be generated and returned by the gateway. It’s highly recommended that you provide your own unique identifier for the request, so it can be used for querying if there’s an unexpected error. Allows any printable ASCII characters, with a length between 5-35 characters.

External Reference

The External Reference is an optional, non-unique identifier that you can provide when creating a resource. Unlike the reference field, which is intended to uniquely identify a single resource, the External Reference is designed for aggregation and cross-system linking.

Common use cases include:

• Grouping related resources: Assign the same External Reference across multiple resources, such as transactions, customers, and payment instruments, to logically group them together. You can then query by this value to retrieve the associated records.
• Linking to external systems: Use the External Reference to store an identifier from your own platform (e.g. an order ID, customer ID, or account number), making it easy to correlate API resources with records in your own system.

Date Formatting

Date

For any field where only the Date part of the DateTime is required, the format will be YYYY-MM-DD. Dates are commonly used when referencing the processing date for a transaction, and unless otherwise stated, the dates will reflect the timezone for Sydney, Australia.
eg. 2023-01-01

{
  "startDate": "2023-01-01",
  "endDate": "2023-01-15"
}

DateTime

The format for any DateTime value in the API will follow the ISO 8601 format YYYY-MM-DDThh:mm:ss[.mmm]TZD. These values are timestamps and are reflected in UTC.
eg. 2022-07-14T10:05:45Z

Where:

• YYYY = four-digit year
• MM = two-digit month (eg 03=March)
• DD = two-digit day of the month (01 through 31)
• T = a set character indicating the start of the time element
• hh = two digits of an hour (00 through 23, AM/PM not included)
• mm = two digits of a minute (00 through 59)
• ss = two digits of a second (00 through 59)
• mmm = three digits of a millisecond (000 through 999)
• TZD = time zone designator (Z or +hh:mm or -hh:mm), the + or - values indicate how far ahead or behind a time zone is from the UTC (Coordinated Universal Time) zone

{
  "createdDateTime": "2022-07-14T10:05:45Z",
  "updatedDateTime": "2022-07-14T11:05:45Z"
}