Skip to content
Global Payments Oceania API Global Payments Oceania API

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 type of token that represents a specific method of payment that a customer can use. For example, a credit card or a bank account (powered by PayTo). A payment instrument token will have a unique Id and some relevant details, depending on the type of instrument.

  • For a card payment instrument, the details will include the cardholder name, card number, and expiry date.
  • For a PayTo payment instrument, the details will include the agreement terms, frequency, amount, etc.

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.

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