Download OpenAPI specification:Download
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.
X-MerchantId required | string <uuid> The ono//connect merchant ID related to the request |
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 |
OK
Bad Request
Internal Server Error
{- "terminal": {
- "serialNumber": "1619900116",
- "terminalModel": "blue_pad55"
}, - "organization": {
- "organizationId": "6770df92-1001-47a2-9ddf-e6a89b902fa0",
- "name": "ACME"
}
}
{- "transactionToken": "rlTLSawdRZasRrrDjgN4xA-ikfqz9bhn51bcduik9g2ititoz8zuba4",
- "merchant": {
- "organizationId": "29d858ec-c6f2-4879-89ba-027688175262",
- "merchantName": "ACME coffee",
- "city": "Cape Town",
- "region": "ZA",
- "country": "ZA",
- "postalCode": "8001",
- "mcc": 5812
}
}
Create a new charge transaction.
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 |
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 | |
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 |
OK
Bad Request
Unauthorized
Internal Server Error
Gateway Timeout
{- "merchantId": "e2c826cb-26da-4527-9d85-8d81bff25705",
- "amountInCents": 1000,
- "currency": "zar",
- "clientTransactionId": "your-unique-reference-id",
- "paymentMethodInfo": {
- "paymentMethod": "card",
- "cardInfo": {
- "tlv": "5F200E4D5...",
- "tlvKSN": "FFFF00A0200001E0001E",
- "transactionData": {
- "encTrack1": "encrypted_track1_data",
- "encTrack2": "encrypted_track2_data",
- "trackksn": "KSN for track data",
- "pinBlock": "encrypted_PIN_data",
- "pinKsn": "KSN for PIN data",
- "key": "value"
}, - "terminal": {
- "serialNumber": "020-123456",
- "terminalModel": "qpos",
- "terminalInfo": {
- "emvConfig": "config-prod",
- "key": "value"
}, - "batteryPercent": 77,
- "versions": {
- "firmwareVersion": "1234",
- "hardwareVersion": "9999"
}
}, - "attemptedInputModes": [
- "swipe",
- "chip"
]
}
}, - "deviceInfo": {
- "manufacturer": "Nokia",
- "model": "5110",
- "os": "S20",
- "osVersion": "1.0"
}, - "appInfo": {
- "appName": "your-pos-app",
- "appVersion": "1.2.33",
- "sdkName": "yourSdk",
- "sdkVersion": "1.23"
}, - "metadata": {
- "staffNumber": "1234",
- "key": "value"
}
}
{- "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": {
- "cardInfo": {
- "issuerResponseData": "",
- "signatureRequired": false,
- "rrn": "458729",
- "authorizationId": "123456",
- "acquirer": "absa",
- "scheme": "visa",
- "clearingMerchantId": "00000103265-5",
- "clearingTerminalId": "98000101",
- "card": {
- "maskedPan": "356999******2211",
- "cardholderName": "J DOE",
- "cardholderVerificationMethod": 2,
- "panEntryMode": 5,
- "expiryYear": "25",
- "expiryMonth": "03",
- "expiryDay": "31"
}
}
}, - "updateAvailable": false
}
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.
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 |
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 |
OK
[- {
- "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": {
- "cardInfo": {
- "issuerResponseData": "",
- "signatureRequired": false,
- "rrn": "458729",
- "authorizationId": "123456",
- "acquirer": "absa",
- "scheme": "visa",
- "clearingMerchantId": "00000103265-5",
- "clearingTerminalId": "98000101",
- "card": {
- "maskedPan": "356999******2211",
- "cardholderName": "J DOE",
- "cardholderVerificationMethod": 2,
- "panEntryMode": 5,
- "expiryYear": "25",
- "expiryMonth": "03",
- "expiryDay": "31"
}
}
}, - "updateAvailable": false
}
]
Provides a means to query the current result information.
transactionId required | string <uuid> The ono//connect generated transaction id for a charge transaction |
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 |
OK
chargeResult
of pending
chargeResult
changesUnauthorized
Internal Server Error
{- "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": {
- "cardInfo": {
- "issuerResponseData": "",
- "signatureRequired": false,
- "rrn": "458729",
- "authorizationId": "123456",
- "acquirer": "absa",
- "scheme": "visa",
- "clearingMerchantId": "00000103265-5",
- "clearingTerminalId": "98000101",
- "card": {
- "maskedPan": "356999******2211",
- "cardholderName": "J DOE",
- "cardholderVerificationMethod": 2,
- "panEntryMode": 5,
- "expiryYear": "25",
- "expiryMonth": "03",
- "expiryDay": "31"
}
}
}, - "updateAvailable": false
}
Provides a means to query the last known result of a charge.
Use this endpoint instead of /v2/charges/{transactionId}/lastResponse
if the POS was
unable to process a response from ono//connect for a prior charge request.
Allows query the last response for a charge, even if the ono//connect transactionId hasn’t been received.
clientTransactionId required | string Transaction reference from the merchant system. This should be unique between transactions |