Method: sendOtp

  • This endpoint enables vendors to send an OTP (One-Time Password) to a user as part of a Virtual Cards enrollment or provisioning flow.

  • The request must include the enrollmentRequestId, challengeOptionId, and standard request header information.

  • Successful responses provide details like maximum verification attempts, send attempts, and OTP expiration timestamp.

  • Error responses, indicated by 4XX or 5XX HTTP status codes, will conform to the ErrorResponse object structure.

  • The API supports multiple response types, including success and various decline reasons like challenge option expiration, send limit exceeded, account locked, or risk-based decline.

Request to the vendor to send an OTP to the user.

If the endpoint encounters an error while processing the request, the response body from this endpoint should be of type ErrorResponse.

An example request looks like:


{
  "requestHeader": {
    "protocolVersion": {
      "major": 1
    },
    "requestId": "BKD0GF23KSD8S23",
    "requestTimestamp": {
      "epochMillis": "1481899949606"
    },
    "paymentIntegratorAccountId": "abcdef123456"
  },
  "enrollmentRequestId": "SFLKJS23542ALFJ",
  "challengeOptionId": "G1MQ0YERJ0Q7LPM"
}

An example success response looks like:


{
  "responseHeader": {
    "responseTimestamp": {
      "epochMillis": "1481899950236"
    }
  },
  "result": {
    "success" :{
      "maxVerificationAttempts": "5",
      "maxSendAttempts": "3",
      "expirationTimestamp": {
         "epochMillis": "1481899960236"
      }
    }
  }
}

HTTP request

POST https://www.integratorhost.example.com/integrator-base-path/virtual-cards-v1/sendOtp

Request body

The request body contains data with the following structure:

JSON representation 
{
  "requestHeader": {
    object (RequestHeader)
  },
  "enrollmentRequestId": string,
  "challengeOptionId": string
}
Fields
requestHeader

object (RequestHeader)

REQUIRED: Common header for all requests.
enrollmentRequestId

string

REQUIRED: A reference to an earlier enrollment request. Specifically, the identifier set in the requestId of the requestHeader sent in the enrollRequest that registered a card for Virtual Cards.

This is a string that has a maximum length of 100 characters.
challengeOptionId

string

REQUIRED: A reference to an OTP challenge option returned in a previous call, indicating that the user has selected this particular OTP option.

This is a string that has a maximum length of 100 characters. Valid characters: [a-zA-Z0-9:_-]

Response body

This method supports multiple return types. For additional information about what 4XX or 5XX HTTP status code to return with an ErrorResponse, consult the ErrorResponse object and HTTP status codes documentation.

Possible response messages
HTTP 200 Status

object (SendOtpResponse)
HTTP 4XX / 5XX Status

object (ErrorResponse)

SendOtpResponse

Response object for the sendotp method.

JSON representation 
{
  "responseHeader": {
    object (ResponseHeader)
  },
  "result": {
    object (SendOtpResult)
  }
}
Fields
responseHeader

object (ResponseHeader)

REQUIRED: Common header for all responses.
result

object (SendOtpResult)

REQUIRED: Contains the result of the request.

SendOtpResult

Details corresponding to the result.

JSON representation 
{

  // Union field result can be only one of the following:
  "success": {
    object (SendOtpSuccessResult)
  },
  "challengeOptionExpired": {
    object (Empty)
  },
  "sendLimitExceeded": {
    object (Empty)
  },
  "accountLocked": {
    object (Empty)
  },
  "riskDeclined": {
    object (Empty)
  }
  // End of list of possible types for union field result.
}
Fields
Union field result. REQUIRED: Contains the possible result types. Exactly one must be set. result can be only one of the following:
success

object (SendOtpSuccessResult)

The request to sendOtp was successful.
challengeOptionExpired

object (Empty)

Declined because the challenge option has expired.
sendLimitExceeded

object (Empty)

Declined because the maximum number of times the OTP can be sent has been exceeded.
accountLocked

object (Empty)

Declined because the user's account has been locked.
riskDeclined

object (Empty)

Declined due to risk.

SendOtpSuccessResult

Details about the success result.

JSON representation 
{
  "maxVerificationAttempts": string,
  "maxSendAttempts": string,
  "expirationTimestamp": {
    object (Timestamp)
  }
}
Fields
maxVerificationAttempts

string (Int64Value format)

REQUIRED The maximum amount of times the OTP can be verified.
maxSendAttempts

string (Int64Value format)

REQUIRED The maximum amount of times the sending the OTP can be requested for this particular challenge option.
expirationTimestamp

object (Timestamp)

REQUIRED The expiration timestamp after which the OTP will no longer be accepted.