Documentation Powered by ReDoc

ono//connect API (2.0.0)

Download OpenAPI specification:Download

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

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

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 last response
post/v2/charges
https://transactions.test.onoconnect.io/v2/charges

Request samples

Content type
application/json
Example
Create a card payment charge
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
Receive a card payment response
Copy
 Expand all Collapse all
{
  • "transactionId": "66ce8ae4-394b-4a10-b10a-5bd24987b996",
  • "chargeResult": "approved",
  • "chargeResultMessage": "Approved or completed successfully",
  • "isoResponseCode": "00",
  • "paymentInfo":
    {
    }
}

Confirm charge

Confirm a transaction has been successfully processed by a device. This includes a 2nd Gen AAC.

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

Request Body schema: application/json

Confirm charge

transactionId
required
string <uuid>

The ono//connect generated transaction id for the charge request

paymentMethodInfo
object (PaymentMethodFinalizationInfo)

Payment method information related to a charge request

Responses

200

OK

  • Success, with payload
400

Bad Request

  • Bad or missing JSON input
  • Retries: Do not retry without adjusting input
401

Unauthorized

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

Not Found

  • Attempted to confirm an unknown transaction
  • Retries: Do not retry
409

Conflict

  • Attempted to confirm a transaction which is not in a confirmable state
  • Retries: Retry with back-off for up to 1 hour only.
500

Internal Server Error

  • May be returned in exceptional cases
  • Retries: Do not retry
post/v2/charges/{transactionId}/confirm
https://transactions.test.onoconnect.io/v2/charges/{transactionId}/confirm

Request samples

Content type
application/json
Example
Confirm a card payment charge
Copy
 Expand all Collapse all
{
  • "transactionId": "66ce8ae4-394b-4a10-b10a-5bd24987b996",
  • "paymentMethodInfo":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{ }

Reject charge

In the case of a 2nd Gen AAC decline, or when a terminal is unable to confirm the transaction you can reject it which will cause it to be reversed.

Allows attempting to clean up a transaction, even if the ono//connect transactionId hasn’t been received

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

Request Body schema: application/json

Reject charge

transactionId
required
string <uuid>

The ono//connect generated transaction id for the charge request

paymentMethodInfo
object (PaymentMethodFinalizationInfo)

Payment method information related to a charge request

Responses

200

OK

  • Success, with payload
400

Bad Request

  • Bad or missing JSON input
  • Retries: Do not retry without adjusting input
401

Unauthorized

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

Not Found

  • Attempted to reject an unknown transaction
  • Retries: Do not retry
409

Conflict

  • Attempted to reject a transaction which is not in a rejectable state
  • Retries: Retry with back-off for up to 1 hour only.
500

Internal Server Error

  • May be returned in exceptional cases
  • Retries: Do not retry
post/v2/charges/{transactionId}/reject
https://transactions.test.onoconnect.io/v2/charges/{transactionId}/reject

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "transactionId": "66ce8ae4-394b-4a10-b10a-5bd24987b996",
  • "paymentMethodInfo":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{ }

Reject charge by clientTransactionId

In the case of a 2nd Gen AAC decline, or when a terminal is unable to confirm the transaction you can reject it which will cause it to be reversed.

Use this endpoint instead of /v2/charges/{transactionId}/reject if the POS was unable to process a response from ono//connect for a prior charge request.

Allows attempting to clean up a transaction, 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

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

Reject charge

transactionId
required
string <uuid>

The ono//connect generated transaction id for the charge request

paymentMethodInfo
object (PaymentMethodFinalizationInfo)

Payment method information related to a charge request

Responses

200

OK

  • Success, with payload
400

Bad Request

  • Bad or missing JSON input
  • Retries: Do not retry without adjusting input
401

Unauthorized

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

Not Found

  • Attempted to reject an unknown transaction
  • Retries: Do not retry
409

Conflict

  • Attempted to reject a transaction which is not in a rejectable state
  • Retries: Retry with back-off for up to 1 hour only.
500

Internal Server Error

  • May be returned in exceptional cases
  • Retries: Do not retry
post/v2/charges/by/clientTransactionId/{clientTransactionId}/reject
https://transactions.test.onoconnect.io/v2/charges/by/clientTransactionId/{clientTransactionId}/reject

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "transactionId": "66ce8ae4-394b-4a10-b10a-5bd24987b996",
  • "paymentMethodInfo":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{ }

Sign a charge

Record a signature against a transaction. This may be called at any point after a transaction has been started, depending on client process flow.

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

Request Body schema: application/json

Sign a charge

transactionId
required
string <uuid>

The ono//connect generated transaction id for the charge request

signature
required
string

The format for the signature is a Base64 encoded data URL with MIME information.

Responses

200

OK

  • Success, with payload
400

Bad Request

  • Bad or missing JSON input
  • Retries: Do not retry without adjusting input
401

Unauthorized

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

Not Found

  • Attempted to submit a signature for an unknown transaction
  • Retries: Do not retry
409

Conflict

  • Attempted to submit signature for a transaction which is not in a state ready to accept a signature
  • Retries: Retry with back-off for up to 1 hour only.
500

Internal Server Error

  • May be returned in exceptional cases
  • Retries: Do not retry
post/v2/charges/{transactionId}/signature
https://transactions.test.onoconnect.io/v2/charges/{transactionId}/signature

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "transactionId": "66ce8ae4-394b-4a10-b10a-5bd24987b996",
  • "signature": "data:image/png;base64,...."
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{ }

Refund charge

Refund an existing charge transaction.

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

Request Body schema: application/json

Refund an existing charge

transactionId
required
string <uuid>

The ono//connect generated transaction id for the charge request

amountInCents
required
integer

The charge amount specified in cents

clientTransactionId
required
string

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

refundMethod
required