ono//connect API (2.0.0)

Download OpenAPI specification:Download

API Support: all@onoconnect.com URL: http://www.onoconnect.com

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

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

Payload

Content type

application/json

Copy

Expand all Collapse all


{"terminal": 
{"serialNumber": "1619900116",
"terminalModel": "blue_pad55"
},
"organization": 
{"organizationId": "6770df92-1001-47a2-9ddf-e6a89b902fa0",
"name": "ACME"
}
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"transactionToken": "rlTLSawdRZasRrrDjgN4xA-ikfqz9bhn51bcduik9g2ititoz8zuba4",
"merchant": 
{"organizationId": "29d858ec-c6f2-4879-89ba-027688175262",
"merchantName": "ACME coffee",
"city": "Cape Town",
"region": "ZA",
"country": "ZA",
"postalCode": "8001",
"mcc": 5812
}
}

charges

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

Create charge

Create a new charge transaction.

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 ISO 4217 reference
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

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

Payload

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

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

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

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

Success, with payload

get/v2/charges

https://api.test.onoconnect.com/v2/charges

Response samples

Content type

application/json

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": 
{"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
}
]

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

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

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

Get charge by clientTransactionId

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.

path Parameters

clientTransactionId

required

string

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