​
Validate Transaction OTP API

This endpoint is used to validate the OTP (One-Time Password) for transaction authentication. It ensures that the customer is authorized to complete the payment by verifying the OTP entered during the process.

​
Request Parameters

Request
curl --request POST \
  --url https://adapter.cepta.co/api/v1/pay/validate-otp \
  --header 'Authorization: <SECRET_KEY>' \
  --header 'Content-Type: application/json' \
  --data '
    {
        "otp": "123456",
        "transactionRef": "TX12345ABC",
        "paymentId": "PAY12345XYZ",
        "md": "merchant_data"
    }
  '

Ensure secure handling of md (merchant data) and token to maintain transaction integrity.

Below is a list of request parameters accepted for validating an API.

​
otp
string
required

otp string Yes The one-time password provided by the customer.

​
transactionRef
string
required

Unique reference for the transaction.

​
paymentId
string
required

Unique identifier for the payment.

​
md
string
required

Merchant data, used for 3D Secure transactions.

​
Validate OTP API Response

A sample response of what to expect when a call is made to the API

Success response
{
  "status": true,
  "message": "OTP validated successfully.",
  "data": {
    "amount": "100.00",
    "transactionIdentifier": "TRX56789",
    "tokenExpiryDate": "2024-12-29T12:22:27.891Z",
    "token": "secure_token_12345",
    "message": "Payment completed.",
    "transactionRef": "TX12345ABC",
    "responseCode": "00",
    "otpRetryCount": 3,
    "paymentId": "PAY12345XYZ",
    "errors": []
  }
}

​
Handling successful API response body

When a transaction has been initiated successfully, there is response data that is returned. This can be in turn to update the customer about the current stage of their transaction.

Below is the list of responses to expect and the usage.

​
status
boolean

Indicates if the OTP validation was successful.

​
message
string

Descriptive message about the result.

​
data
object

Contains detailed transaction data.

​
amount
string

Amount for the transaction

​
transactionIdentifier
string

Identifier for the transaction.

​
tokenExpiryDate
string (ISO 8601)

Expiry date of the token.

​
token
string

Token generated for the transaction.

​
transactionRef
string

Reference of the validated transaction

​
responseCode
string

Response code from the payment processor

​
otpRetryCount
number

Number of OTP retries remaining.

​
paymentId
string

Identifier for the validated payment.

​
errors
array

Array of error objects, if any.

​
errorCode
string

Specific error code, if applicable.

​
message
string

Description of the error.

​
Handling failed API response body

When your response message is returned as a failed response, the response.data will return an array containing details of the error. You can show this to your customer to notify them of what is wrong.

Below is a sample failed response data.

Failed response
{
  "status": false,
  "message": "OTP validation failed.",
  "data": {
    "amount": "0",
    "transactionIdentifier": "",
    "tokenExpiryDate": "",
    "token": "",
    "message": "Invalid OTP.",
    "transactionRef": "TX12345ABC",
    "responseCode": "01",
    "otpRetryCount": 2,
    "paymentId": "PAY12345XYZ",
    "errors": [
      {
        "errorCode": "INVALID_OTP",
        "message": "The provided OTP is incorrect."
      }
    ]
  }
}
Initialize TransactionConfirm Transaction