Skip to content
API requests
/
/Operations/One Time Passcode

One Time Passcode API (1.0.0)

The One Time Passcode (OTP) API is a JSON-based RESTful API that enables merchants to verify OTP codes sent to buyers.

Download OpenAPI description
otp_api.json
otp_api.yaml
Overview
URL

https://www.ratepay.com/

Ratepay GmbH

info@ratepay.com

Languages
Servers
Ratepay Production Platform

https://api.ratepay.com/

Ratepay Integration Platform

https://api-integration.ratepay.com/

One Time Passcode

Operations

Validate an OTP code

Request

Security
Bearer
Path
transactionIdstringrequired

The id of the transaction that initialized the OTP process

Example: 684CWYHCK05X2CN5K_N6
Bodyapplication/jsonrequired
otp_codestringnon-emptyrequired

The OTP code given by the customer

Example: 15316
curl -i -X POST \
  https://api.ratepay.com/transaction/management/2fa/v1/verify/684CWYHCK05X2CN5K_N6 \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "otp_code": 15316
  }'

Responses

OTP code verified successfully

Bodyapplication/json
timestampstring(date-time)required

When the response was generated

regeneration_possible_in_secondsinteger(int64)

The time until another OTP can be sent. Might be null in error responses or when the OTP is verified.

ratepay_transaction_idstringnon-emptyrequired

The id of the transaction that was tied to the OTP process

Example: "684CWYHCK05X2CN5K_N6"
resultstring(ApiResponseDto_result)non-emptyrequired
Enum"otp_sent""unexpected_client_input""otp_verified""otp_regenerated""unexpected_server_error""otp_exists""otp_failed""verify_attempt_failed""no_more_verification_attempts_left""transaction_not_found"
messageany(ApiResponseDto_message)required
_linksobject(Links)
Response
application/json
{
  "timestamp": "2025-10-02T09:14:37.507714Z",
  "ratepayTransactionId": "684CWYHCK05X2CN5K_N6",
  "result": "otp_verified",
  "message": {
    "en": "Your code has been successfully verified.",
    "de": "Ihr Code wurde erfolgreich überprüft."
  },
  "links": [
    { … }
  ]
}

Regenerate OTP code for an active OTP process

Request

Security
Bearer
Path
transactionIdstringnon-emptyrequired

The id of the transaction that initialized the OTP process

Example: 684CWYHCK05X2CN5K_N6
curl -i -X POST \
  https://api.ratepay.com/transaction/management/2fa/v1/regenerate/684CWYHCK05X2CN5K_N6 \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

OTP code was regenerated successfully

Bodyapplication/json
timestampstring(date-time)required

When the response was generated

regeneration_possible_in_secondsinteger(int64)

The time until another OTP can be sent. Might be null in error responses or when the OTP is verified.

ratepay_transaction_idstringnon-emptyrequired

The id of the transaction that was tied to the OTP process

Example: "684CWYHCK05X2CN5K_N6"
resultstring(ApiResponseDto_result)non-emptyrequired
Enum"otp_sent""unexpected_client_input""otp_verified""otp_regenerated""unexpected_server_error""otp_exists""otp_failed""verify_attempt_failed""no_more_verification_attempts_left""transaction_not_found"
messageany(ApiResponseDto_message)required
time_to_live_in_secondsinteger(int64)required

The time until the OTP process will expire and the OTP will be invalid.

_linksobject(Links)
Response
application/json
{
  "timestamp": "2025-10-02T09:14:37.507764Z",
  "regenerationPossibleInSeconds": 60,
  "ratepayTransactionId": "684CWYHCK05X2CN5K_N6",
  "result": "otp_sent",
  "message": {
    "en": "The code has been sent to your phone number 0049123411223344.",
    "de": "Der Code wurde an Ihre Telefonnummer 0049123411223344 gesendet."
  },
  "timeToLiveInSeconds": 120,
  "links": [
    { … },
    { … }
  ]
}