ono//connect API (2.0.0)

Download OpenAPI specification:Download

auth

Create a new session token

When it is not possible to use your own systems to generate a token then this can be done by onoConnect.

In this scenario ono//connect authenticates the POS with the data provided below and on successful authentication will return a token.

header Parameters
X-MerchantId
required
string <uuid>

The ono//connect merchant ID related to the request

Request Body schema: application/json

Create a new session token for a user identified by their terminal information

terminal
required
object (ClientTerminal)

Terminal details related to this transaction

organization
object (OrganizationInfo)

Organization information

Responses

200

OK

  • Device successfully authenticated
400

Bad Request

  • Bad or missing JSON input
500

Internal Server Error

  • May be returned in exceptional cases
post/v2/auth/loginDevice
https://api.test.onoconnect.com/v2/auth/loginDevice

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "terminal":
    {
    },
  • "organization":
    {
    }
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "transactionToken": "rlTLSawdRZasRrrDjgN4xA-ikfqz9bhn51bcduik9g2ititoz8zuba4",
  • "merchant":
    {
    }
}

charges

Enpoints used by mobile apps or terminals to manage charge transactions.

Create charge

Create a new charge transaction.

path Parameters
receiptData
boolean
Example: false

Indicate whether the charge response should include receipt information. By not including receipt information the response payload size is reduced to the most critical data elements.

By default this is set to true.

header Parameters
X-MerchantId
required
string <uuid>

The ono//connect merchant ID related to the request

X-TransactionToken
required
string

The transaction token assigned to the merchant. Generated either by logging in to ono//connect or supplied to ono//connect using the user onboarding API's

Request Body schema: application/json

Create a new charge

merchantId
required
string <uuid>

The ono//connect assigned merchant ID

amountInCents
required
integer

The charge amount specified in cents

currency
required
string

The ISO 4217 currency code for this transaction

clientTransactionId
required
string

Transaction reference from the merchant system. This should be unique between transactions

priorClientTransactionId
string

Should this be a retry of a previous transaction then this should be populated with the prior clientTransactionId for the previous charge request

paymentMethodInfo
required
object (PaymentMethodRequestInfo)

Payment method information related to a charge request

deviceInfo
required
object (DeviceInfo)

Device related information for the transaction

appInfo
required
object (AppInfo)

App related information for the transaction

metadata
object

A key/value collection of arbitrary data to be stored with the charge, and which will be returned in the charge result callback

Responses

200

OK

  • Transactions was successfully processed end-to-end
  • Transaction may still have been rejected by upstream banks or switches, inspect ISO response code
  • If a transaction is rejected by a pre-processing rule. Take action based on returned custom ISO response code and submit new transaction.
400

Bad Request

  • Bad or missing JSON input
  • If the terminal ID is not recognised, or is not linked to a merchant
  • If card data cannot be read or is badly formatted
  • Retries: Do not retry without adjusting input
401

Unauthorized

  • Bad or deleted token or merchant
  • Retries: Do not retry
500

Internal Server Error

  • May be returned in exceptional cases
  • Retries: Do not retry
504

Gateway Timeout

  • If an upstream backend takes too long to respond to a request
  • Retries: Do not retry, query get charge
post/v2/charges
https://api.test.onoconnect.com/v2/charges

Request samples

Content type
application/json
Example
Copy
Expand all Collapse all
{
  • "merchantId": "e2c826cb-26da-4527-9d85-8d81bff25705",
  • "amountInCents": 1000,
  • "currency": "zar",
  • "clientTransactionId": "your-unique-reference-id",
  • "paymentMethodInfo":
    {
    },
  • "deviceInfo":
    {
    },
  • "appInfo":
    {
    },
  • "metadata":
    {
    }
}

Response samples

Content type
application/json
Example
Copy
Expand all Collapse all
{
  • "transactionId": "66ce8ae4-394b-4a10-b10a-5bd24987b996",
  • "clientTransactionId": "your-unique-reference-id",
  • "chargeResult": "approved",
  • "chargeResultMessage": "Approved or completed successfully",
  • "isoResponseCode": "00",
  • "displayAmount": "R 1000.00",
  • "amountInCents": 1000,
  • "currency": "zar",
  • "transactionTime": "2020-11-09T13:37:01.123",
  • "paymentInfo":
    {
    },
  • "updateAvailable": false
}

Get a list of recently performed transactions

Per-merchant recent transaction history can be requested should the user wish to browse or reprint recent transactions.

Transaction history is currently maintained for up to 24 hours.

path Parameters
offset
required
integer <int32>

Set the starting transaction index - 0-based index. Default 0

limit
required
integer <int32>

Limits how many records are returned per request. Default 10

serialNumber
string

The terminal serial number

receiptData
boolean
Example: false

Indicate whether the charge response should include receipt information. By not including receipt information the response payload size is reduced to the most critical data elements.

By default this is set to true.

header Parameters
X-MerchantId
required
string <uuid>

The ono//connect merchant ID related to the request

X-TransactionToken
required
string

The transaction token assigned to the merchant. Generated either by logging in to ono//connect or supplied to ono//connect using the user onboarding API's

Responses

200

OK

  • Success, with payload
get/v2/charges
https://api.test.onoconnect.com/v2/charges

Response samples

Content type
application/json
Example
Copy
Expand all Collapse all
[
  • {
    }
]

Get charge

Provides a means to query the current result information.

path Parameters
transactionId
required
string <uuid>

The ono//connect generated transaction id for a charge transaction

receiptData
boolean
Example: false

Indicate whether the charge response should include receipt information. By not including receipt information the response payload size is reduced to the most critical data elements.

By default this is set to true.

header Parameters
X-MerchantId
required
string <uuid>

The ono//connect merchant ID related to the request

X-TransactionToken
required
string

The transaction token assigned to the merchant. Generated either by logging in to ono//connect or supplied to ono//connect using the user onboarding API's

Responses

200

OK

  • Success, with payload
  • For a chargeResult of pending
    1. If the charge relates to a card payment charge, consider resubmitting
    2. If the charge relates to a Masterpass charge, keep querying this endpoint until the chargeResult changes
401

Unauthorized

  • Bad or deleted token or merchant
  • Retries: Do not retry
500

Internal Server Error

  • May be returned in exceptional cases
  • Retries: Do not retry
get/v2/charges/{transactionId}
https://api.test.onoconnect.com/v2/charges/{transactionId}

Response samples

Content type
application/json
Example
Copy
Expand all Collapse all
{
  • "transactionId": "66ce8ae4-394b-4a10-b10a-5bd24987b996",
  • "clientTransactionId": "your-unique-reference-id",
  • "chargeResult": "approved",
  • "chargeResultMessage": "Approved or completed successfully",
  • "isoResponseCode": "00"