The Verify API helps you to implement 2FA (two-factor authentication) in your applications. This is useful for:
Use Verify request to generate and send a PIN to your user:
Create a request to send a verification code to your user.
Check the status
field in the response to ensure that your request was successful (zero is success).
Use the request_id
field in the response for the Verify check.
Note that this endpoint is available by GET
request as well as POST
.
POST
https://api.nexmo.com/verify/:format
Host
https://api.nexmo.com
POST
/verify/:format
The response format.
Must be one of:json
or xml
You can find your API key in your account dashboard
You can find your API secret in your account dashboard
The mobile or landline phone number to verify. Unless you are setting country
explicitly, this number must be in E.164 format.
If you do not provide number
in international format or you are not sure if number
is correctly formatted, specify the two-character country code in country
. Verify will then format the number for you.
An 18-character alphanumeric string you can use to personalize the verification request SMS body, to help users identify your company or application name. For example: "Your Acme Inc
PIN is ..."
An 11-character alphanumeric string that represents the identity of the sender of the verification request. Depending on the destination of the phone number you are sending the verification SMS to, restrictions might apply.
The length of the verification code.
Must be one of:4
or 6
By default, the SMS or text-to-speech (TTS) message is generated in the locale that matches the number
. For example, the text message or TTS message for a 33*
number is sent in French. Use this parameter to explicitly control the language used for the Verify request. A list of languages is available: https://developer.nexmo.com/verify/guides/verify-languages
ar-xa
, cs-cz
, cy-cy
, cy-gb
, da-dk
, de-de
, el-gr
, en-au
, en-gb
, en-in
, en-us
, es-es
, es-mx
, es-us
, fi-fi
, fil-ph
, fr-ca
, fr-fr
, hi-in
, hu-hu
, id-id
, is-is
, it-it
, ja-jp
, ko-kr
, nb-no
, nl-nl
, pl-pl
, pt-br
, pt-pt
, ro-ro
, ru-ru
, sv-se
, th-th
, tr-tr
, vi-vn
, yue-cn
, zh-cn
or zh-tw
How long the generated verification code is valid for, in seconds. When you specify both pin_expiry
and next_event_wait
then pin_expiry
must be an integer multiple of next_event_wait
otherwise pin_expiry
is defaulted to equal next_event_wait. See changing the event timings.
Specifies the wait time in seconds between attempts to deliver the verification code.
Selects the predefined sequence of SMS and TTS (Text To Speech) actions to use in order to convey the PIN to your user. For example, an id of 1 identifies the workflow SMS - TTS - TTS. For a list of all workflows and their associated ids, please visit the developer portal.
Must be one of:1
, 2
, 3
, 4
, 5
, 6
or 7
The unique ID of the Verify request. You need this request_id
for the Verify check.
Indicates the outcome of the request; zero is success
The unique ID of the Verify request. This may be blank in an error situation
Code | Text | Description |
---|---|---|
0 | Success | The request was successfully accepted by Vonage. |
1 | Throttled | You are trying to send more than the maximum of 30 requests per second. |
2 | Your request is incomplete and missing the mandatory parameter $parameter
|
The stated parameter is missing. |
3 | Invalid value for parameter $parameter
|
Invalid value for parameter. If you see Facility not allowed in the error text, check that you are using the correct Base URL in your request. |
4 | Invalid credentials were provided | The supplied API key or secret in the request is either invalid or disabled. |
5 | Internal Error | An error occurred processing this request in the Cloud Communications Platform. |
6 | The Vonage platform was unable to process this message for the following reason: $reason
|
The request could not be routed. |
7 | The number you are trying to verify is blacklisted for verification. | |
8 | The api_key you supplied is for an account that has been barred from submitting messages. | |
9 | Partner quota exceeded | Your account does not have sufficient credit to process this request. |
10 | Concurrent verifications to the same number are not allowed | |
15 | The destination number is not in a supported network | The request has been rejected. Find out more about this error in the Knowledge Base |
20 | This account does not support the parameter: pin_code. | Only certain accounts have the ability to set the pin_code . Please contact your account manager for more information. |
29 | Non-Permitted Destination | Your Vonage account is still in demo mode. While in demo mode you must add target numbers to the approved list for your account. Add funds to your account to remove this limitation. |
0
, 1
, 2
, 3
, 4
, 5
, 6
, 7
, 8
, 9
, 10
, 15
, 20
or 29
If status
is non-zero, this explains the error encountered.
The unique ID of the Verify request. You need this request_id
for the Verify check.
Indicates the outcome of the request; zero is success
The unique ID of the Verify request. This may be blank in an error situation
Code | Text | Description |
---|---|---|
0 | Success | The request was successfully accepted by Vonage. |
1 | Throttled | You are trying to send more than the maximum of 30 requests per second. |
2 | Your request is incomplete and missing the mandatory parameter $parameter
|
The stated parameter is missing. |
3 | Invalid value for parameter $parameter
|
Invalid value for parameter. If you see Facility not allowed in the error text, check that you are using the correct Base URL in your request. |
4 | Invalid credentials were provided | The supplied API key or secret in the request is either invalid or disabled. |
5 | Internal Error | An error occurred processing this request in the Cloud Communications Platform. |
6 | The Vonage platform was unable to process this message for the following reason: $reason
|
The request could not be routed. |
7 | The number you are trying to verify is blacklisted for verification. | |
8 | The api_key you supplied is for an account that has been barred from submitting messages. | |
9 | Partner quota exceeded | Your account does not have sufficient credit to process this request. |
10 | Concurrent verifications to the same number are not allowed | |
15 | The destination number is not in a supported network | The request has been rejected. Find out more about this error in the Knowledge Base |
20 | This account does not support the parameter: pin_code. | Only certain accounts have the ability to set the pin_code . Please contact your account manager for more information. |
29 | Non-Permitted Destination | Your Vonage account is still in demo mode. While in demo mode you must add target numbers to the approved list for your account. Add funds to your account to remove this limitation. |
0
, 1
, 2
, 3
, 4
, 5
, 6
, 7
, 8
, 9
, 10
, 15
, 20
or 29
If status
is non-zero, this explains the error encountered.
POST /verify/:format HTTP/1.1
Host: api.nexmo.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 80
api_key=abcd1234&api_secret=Sup3rS3cr3t%21%21&number=447700900000&brand=Acme+Inc
POST /verify/:format HTTP/1.1
Host: api.nexmo.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 178
api_key=abcd1234&api_secret=Sup3rS3cr3t%21%21&number=447700900000&country=GB&brand=Acme+Inc&sender_id=ACME&code_length=6&lg=en-us&pin_expiry=240&next_event_wait=120&workflow_id=4
{
"request_id": "abcdef0123456789abcdef0123456789",
"status": "0"
}
{
"request_id": "",
"status": "2",
"error_text": "Your request is incomplete and missing the mandatory parameter `number`"
}
<?xml version="1.0" encoding="UTF-8"?>
<verify_response>
<request_id>abcdef0123456789abcdef0123456789</request_id>
<status>0</status>
</verify_response>
<?xml version="1.0" encoding="UTF-8"?>
<verify_response>
<request_id/>
<status>2</status>
<error_text>
Your request is incomplete and missing the mandatory parameter `number`
</error_text>
</verify_response>
Use Verify check to confirm that the PIN you received from your user matches the one sent by Vonage in your Verify request.
code
that your user supplied, with the corresponding request_id
from the Verify request.status
of the response to determine if the code the user supplied matches the one sent by Vonage.Note that this endpoint is available by GET
request as well as POST
.
POST
https://api.nexmo.com/verify/check/:format
Host
https://api.nexmo.com
POST
/verify/check/:format
The response format.
Must be one of:json
or xml
You can find your API key in your account dashboard
You can find your API secret in your account dashboard
The Verify request to check. This is the request_id
you received in the response to the Verify request.
The verification code entered by your user.
(This field is no longer used)
The request_id
that you received in the response to the Verify request and used in the Verify check request.
The ID of the verification event, such as an SMS or TTS call.
A value of 0
indicates that your user entered the correct code. If it is non-zero, check the error_text
.
The cost incurred for this request.
The currency code.
This field may not be present, depending on your pricing model. The
value indicates the cost (in EUR) of the calls made and messages sent
for the verification process. This value may be updated during and
shortly after the request completes because user input events can
overlap with message/call events. When this field is present, the total
cost of the verification is the sum of this field and the price
field.
The request_id
that you received in the response to the Verify request and used in the Verify check request.
Code | Text | Description |
---|---|---|
0 | Success | The request was successfully accepted by Vonage. |
1 | Throttled | You are trying to send more than the maximum of 30 requests per second. |
2 | Your request is incomplete and missing the mandatory parameter $parameter
|
The stated parameter is missing. |
3 | Invalid value for parameter $parameter
|
Invalid value for parameter. If you see Facility not allowed in the error text, check that you are using the correct Base URL in your request. |
4 | Invalid credentials were provided | The supplied API key or secret in the request is either invalid or disabled. |
5 | Internal Error | An error occurred processing this request in the Cloud Communications Platform. |
6 | The Vonage platform was unable to process this message for the following reason: $reason
|
The request could not be routed. |
16 | The code inserted does not match the expected value | |
17 | The wrong code was provided too many times | You can run Verify check on a specific request_id up to three times unless a new verification code is generated. If you check a request more than three times, it is set to FAILED and you cannot check it again. |
0
, 1
, 2
, 3
, 4
, 5
, 6
, 16
or 17
If the status
is non-zero, this explains the error encountered.
The request_id
that you received in the response to the Verify request and used in the Verify check request.
The ID of the verification event, such as an SMS or TTS call.
A value of 0
indicates that your user entered the correct code. If it is non-zero, check the error_text
.
The cost incurred for this request.
The currency code.
This field may not be present, depending on your pricing model. The
value indicates the cost (in EUR) of the calls made and messages sent
for the verification process. This value may be updated during and
shortly after the request completes because user input events can
overlap with message/call events. When this field is present, the total
cost of the verification is the sum of this field and the price
field.
The request_id
that you received in the response to the Verify request and used in the Verify check request.
Code | Text | Description |
---|---|---|
0 | Success | The request was successfully accepted by Vonage. |
1 | Throttled | You are trying to send more than the maximum of 30 requests per second. |
2 | Your request is incomplete and missing the mandatory parameter $parameter
|
The stated parameter is missing. |
3 | Invalid value for parameter $parameter
|
Invalid value for parameter. If you see Facility not allowed in the error text, check that you are using the correct Base URL in your request. |
4 | Invalid credentials were provided | The supplied API key or secret in the request is either invalid or disabled. |
5 | Internal Error | An error occurred processing this request in the Cloud Communications Platform. |
6 | The Vonage platform was unable to process this message for the following reason: $reason
|
The request could not be routed. |
16 | The code inserted does not match the expected value | |
17 | The wrong code was provided too many times | You can run Verify check on a specific request_id up to three times unless a new verification code is generated. If you check a request more than three times, it is set to FAILED and you cannot check it again. |
0
, 1
, 2
, 3
, 4
, 5
, 6
, 16
or 17
If the status
is non-zero, this explains the error encountered.
POST /verify/check/:format HTTP/1.1
Host: api.nexmo.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 99
api_key=abcd1234&api_secret=Sup3rS3cr3t%21%21&request_id=abcdef0123456789abcdef0123456789&code=1234
POST /verify/check/:format HTTP/1.1
Host: api.nexmo.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 122
api_key=abcd1234&api_secret=Sup3rS3cr3t%21%21&request_id=abcdef0123456789abcdef0123456789&code=1234&ip_address=123.0.0.255
{
"request_id": "abcdef0123456789abcdef0123456789",
"event_id": "0A00000012345678",
"status": "0",
"price": "0.10000000",
"currency": "EUR",
"estimated_price_messages_sent": "0.03330000"
}
{
"request_id": "abcdef0123456789abcdef0123456789",
"status": "16",
"error_text": "The code inserted does not match the expected value"
}
<?xml version="1.0" encoding="UTF-8"?>
<verify_response>
<request_id>abcdef0123456789abcdef0123456789</request_id>
<event_id>0A00000012345678</event_id>
<status>0</status>
<price>0.10000000</price>
<currency>EUR</currency>
<estimated_price_messages_sent>0.03330000</estimated_price_messages_sent>
</verify_response>
<?xml version="1.0" encoding="UTF-8"?>
<verify_response>
<request_id>abcdef0123456789abcdef0123456789</request_id>
<status>16</status>
<error_text>
The code inserted does not match the expected value
</error_text>
</verify_response>
Use Verify search to check the status of past or current verification requests:
request_id
s of the verification requests you are interested in.status
of each verification request in the checks
array of the response object to determine the outcome.Note that this endpoint is available by POST
request as well as GET
.
GET
https://api.nexmo.com/verify/search/:format
Host
https://api.nexmo.com
GET
/verify/search/:format
The response format.
Must be one of:json
or xml
You can find your API key in your account dashboard
You can find your API secret in your account dashboard
The request_id
you received in the Verify Request Response. Required if request_ids
not provided.
More than one request_id
. Each request_id
is a new parameter in the Verify Search request. Required if request_id
not provided.
The request_id
that you received in the response to the Verify request and used in the Verify search request.
The Vonage account ID the request was for.
Code | Description |
---|---|
IN PROGRESS | The search is still in progress. |
SUCCESS | Your user entered a correct verification code. |
FAILED | Your user entered an incorrect code more than three times. |
EXPIRED | Your user did not enter a code before the pin_expiry time elapsed. |
CANCELLED | The verification process was cancelled by a Verify control request. |
IN PROGRESS
, SUCCESS
, FAILED
, EXPIRED
or CANCELLED
The phone number this verification request was used for.
The cost incurred for this verification request.
The currency code.
The sender_id
you provided in the Verify request.
The date and time the verification request was submitted, in the following format YYYY-MM-DD HH:MM:SS.
The date and time the verification request was completed. This response parameter is in the following format YYYY-MM-DD HH:MM:SS.
The time the first verification attempt was made, in the following format YYYY-MM-DD HH:MM:SS.
The time the last verification attempt was made, in the following format YYYY-MM-DD HH:MM:SS.
The list of checks made for this verification and their outcomes.
The date and time this check was received (in the format YYYY-MM-DD HH:MM:SS)
The code supplied with this check request
VALID
or INVALID
The IP address, if available (this field is no longer used).
The events that have taken place to verify this number, and their unique identifiers.
tts
or sms
This field may not be present, depending on your pricing model. The
value indicates the cost (in EUR) of the calls made and messages sent
for the verification process. This value may be updated during and
shortly after the request completes because user input events can
overlap with message/call events. When this field is present, the total
cost of the verification is the sum of this field and the price
field.
The request_id
that you received in the response to the Verify request and used in the Verify search request. May be empty in an error situation.
Code | Description |
---|---|
IN PROGRESS | The search is still in progress. |
SUCCESS | Your user entered a correct verification code. |
FAILED | Your user entered an incorrect code more than three times. |
EXPIRED | Your user did not enter a code before the pin_expiry time elapsed. |
CANCELLED | The verification process was cancelled by a Verify control request. |
101 | You supplied an invalid request_id , or the data is not available. Note that for recently-completed requests, there can be a delay of up to 1 minute before the results are available in search. |
IN PROGRESS
, FAILED
, EXPIRED
, CANCELLED
or 101
If status
is not SUCCESS
, this message explains the issue encountered.
The request_id
that you received in the response to the Verify request and used in the Verify search request.
The Vonage account ID the request was for.
Code | Description |
---|---|
IN PROGRESS | The search is still in progress. |
SUCCESS | Your user entered a correct verification code. |
FAILED | Your user entered an incorrect code more than three times. |
EXPIRED | Your user did not enter a code before the pin_expiry time elapsed. |
CANCELLED | The verification process was cancelled by a Verify control request. |
IN PROGRESS
, SUCCESS
, FAILED
, EXPIRED
or CANCELLED
The phone number this verification request was used for.
The cost incurred for this verification request.
The currency code.
The sender_id
you provided in the Verify request.
The date and time the verification request was submitted, in the following format YYYY-MM-DD HH:MM:SS.
The date and time the verification request was completed. This response parameter is in the following format YYYY-MM-DD HH:MM:SS.
The time the first verification attempt was made, in the following format YYYY-MM-DD HH:MM:SS.
The time the last verification attempt was made, in the following format YYYY-MM-DD HH:MM:SS.
The list of checks made for this verification and their outcomes.
The date and time this check was received (in the format YYYY-MM-DD HH:MM:SS)
The code supplied with this check request
VALID
or INVALID
The IP address, if available (this field is no longer used).
The events that have taken place to verify this number, and their unique identifiers.
tts
or sms
This field may not be present, depending on your pricing model. The
value indicates the cost (in EUR) of the calls made and messages sent
for the verification process. This value may be updated during and
shortly after the request completes because user input events can
overlap with message/call events. When this field is present, the total
cost of the verification is the sum of this field and the price
field.
The request_id
that you received in the response to the Verify request and used in the Verify search request. May be empty in an error situation.
Code | Description |
---|---|
IN PROGRESS | The search is still in progress. |
SUCCESS | Your user entered a correct verification code. |
FAILED | Your user entered an incorrect code more than three times. |
EXPIRED | Your user did not enter a code before the pin_expiry time elapsed. |
CANCELLED | The verification process was cancelled by a Verify control request. |
101 | You supplied an invalid request_id , or the data is not available. Note that for recently-completed requests, there can be a delay of up to 1 minute before the results are available in search. |
IN PROGRESS
, FAILED
, EXPIRED
, CANCELLED
or 101
If status
is not SUCCESS
, this message explains the issue encountered.
{
"request_id": "abcdef0123456789abcdef0123456789",
"account_id": "abcdef01",
"status": "IN PROGRESS",
"number": "447700900000",
"price": "0.10000000",
"currency": "EUR",
"sender_id": "mySenderId",
"date_submitted": "2020-01-01 12:00:00",
"date_finalized": "2020-01-01 12:00:00",
"first_event_date": "2020-01-01 12:00:00",
"last_event_date": "2020-01-01 12:00:00",
"checks": [
{
"date_received": "2020-01-01 12:00:00",
"code": "987654",
"status": "abc123",
"ip_address": "123.0.0.255"
}
],
"events": [
{
"type": "abc123",
"id": "abc123"
}
],
"estimated_price_messages_sent": "0.03330000"
}
{
"request_id": "abcdef0123456789abcdef0123456789",
"status": "IN PROGRESS",
"error_text": "No response found"
}
<?xml version="1.0" encoding="UTF-8"?>
<verify_request>
<request_id>abcdef0123456789abcdef0123456789</request_id>
<account_id>abcdef01</account_id>
<status>IN PROGRESS</status>
<number>447700900000</number>
<price>0.10000000</price>
<currency>EUR</currency>
<sender_id>mySenderId</sender_id>
<date_submitted>2020-01-01 12:00:00</date_submitted>
<date_finalized>2020-01-01 12:00:00</date_finalized>
<first_event_date>2020-01-01 12:00:00</first_event_date>
<last_event_date>2020-01-01 12:00:00</last_event_date>
<checks>
<check>
<date_received>2020-01-01 12:00:00</date_received>
<code>987654</code>
<status>abc123</status>
<ip_address>123.0.0.255</ip_address>
</check>
</checks>
<events>
<event>
<type>abc123</type>
<id>abc123</id>
</event>
</events>
<estimated_price_messages_sent>0.03330000</estimated_price_messages_sent>
</verify_request>
<?xml version="1.0" encoding="UTF-8"?>
<verify_request>
<request_id>abcdef0123456789abcdef0123456789</request_id>
<status>IN PROGRESS</status>
<error_text>No response found</error_text>
</verify_request>
Control the progress of your Verify requests. To cancel an existing Verify request, or to trigger the next verification event:
Send a Verify control request with the appropriate command (cmd
) for what you want to achieve.
Check the status
in the response.
Note that this endpoint is available by GET
request as well as POST
.
POST
https://api.nexmo.com/verify/control/:format
Host
https://api.nexmo.com
POST
/verify/control/:format
The response format.
Must be one of:json
or xml
You can find your API key in your account dashboard
You can find your API secret in your account dashboard
The request_id
you received in the response to the Verify request.
The possible commands are cancel
to request cancellation of the verification process, or trigger_next_event
to advance to the next verification event (if any). Cancellation is only possible 30 seconds after the start of the verification request and before the second event (either TTS or SMS) has taken place.
cancel
or trigger_next_event
cmd |
Code | Description |
---|---|---|
Any | 0 | Success |
The cmd
you sent in the request.
cancel
or trigger_next_event
Code | Text | Description |
---|---|---|
0 | Success | The request was successfully accepted by Vonage. |
1 | Throttled | You are trying to send more than the maximum of 30 requests per second. |
2 | Your request is incomplete and missing the mandatory parameter $parameter
|
The stated parameter is missing. |
3 | Invalid value for parameter $parameter
|
Invalid value for parameter. If you see Facility not allowed in the error text, check that you are using the correct Base URL in your request. |
4 | Invalid credentials were provided | The supplied API key or secret in the request is either invalid or disabled. |
5 | Internal Error | An error occurred processing this request in the Cloud Communications Platform. |
6 | The Vonage platform was unable to process this message for the following reason: $reason
|
The request could not be routed. |
8 | The api_key you supplied is for an account that has been barred from submitting messages. | |
9 | Partner quota exceeded | Your account does not have sufficient credit to process this request. |
19 | For cancel : Either you have not waited at least 30 secs after sending a Verify request before cancelling or Verify has made too many attempts to deliver the verification code for this request and you must now wait for the process to complete. For trigger_next_event : All attempts to deliver the verification code for this request have completed and there are no remaining events to advance to. |
0
, 1
, 2
, 3
, 4
, 5
, 6
, 8
, 9
or 19
If the status
is non-zero, this explains the error encountered.
cmd |
Code | Description |
---|---|---|
Any | 0 | Success |
The cmd
you sent in the request.
cancel
or trigger_next_event
Code | Text | Description |
---|---|---|
0 | Success | The request was successfully accepted by Vonage. |
1 | Throttled | You are trying to send more than the maximum of 30 requests per second. |
2 | Your request is incomplete and missing the mandatory parameter $parameter
|
The stated parameter is missing. |
3 | Invalid value for parameter $parameter
|
Invalid value for parameter. If you see Facility not allowed in the error text, check that you are using the correct Base URL in your request. |
4 | Invalid credentials were provided | The supplied API key or secret in the request is either invalid or disabled. |
5 | Internal Error | An error occurred processing this request in the Cloud Communications Platform. |
6 | The Vonage platform was unable to process this message for the following reason: $reason
|
The request could not be routed. |
8 | The api_key you supplied is for an account that has been barred from submitting messages. | |
9 | Partner quota exceeded | Your account does not have sufficient credit to process this request. |
19 | For cancel : Either you have not waited at least 30 secs after sending a Verify request before cancelling or Verify has made too many attempts to deliver the verification code for this request and you must now wait for the process to complete. For trigger_next_event : All attempts to deliver the verification code for this request have completed and there are no remaining events to advance to. |
0
, 1
, 2
, 3
, 4
, 5
, 6
, 8
, 9
or 19
If the status
is non-zero, this explains the error encountered.
POST /verify/control/:format HTTP/1.1
Host: api.nexmo.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 100
api_key=abcd1234&api_secret=Sup3rS3cr3t%21%21&request_id=abcdef0123456789abcdef0123456789&cmd=cancel
{
"status": "0",
"command": "cancel"
}
{
"status": "6",
"error_text": "The requestId 'abcdef0123456789abcdef' does not exist or its no longer active."
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
<status>0</status>
<command>cancel</command>
</response>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<status>6</status>
<error_text>
The requestId 'abcdef0123456789abcdef' does not exist or its no longer active.
</error_text>
</response>
Use Verify request to generate and send a PIN to your user to authorize a payment:
1. Create a request to send a verification code to your user.
2. Check the status
field in the response to ensure that your request was successful (zero is success).
3. Use the request_id
field in the response for the Verify check.
(Please note that XML format is not supported for the Payment Services Directive endpoint at this time.)
POST
https://api.nexmo.com/verify/psd2/:format
Host
https://api.nexmo.com
POST
/verify/psd2/:format
The response format.
Must be one of:json
or xml
You can find your API key in your account dashboard
You can find your API secret in your account dashboard
The mobile or landline phone number to verify. Unless you are setting country
explicitly, this number must be in E.164 format.
If you do not provide number
in international format or you are not sure if number
is correctly formatted, specify the two-character country code in country
. Verify will then format the number for you.
An alphanumeric string to indicate to the user the name of the recipient that they are confirming a payment to.
The decimal amount of the payment to be confirmed, in Euros
The length of the verification code.
Must be one of:4
or 6
By default, the SMS or text-to-speech (TTS) message is generated in the locale that matches the number
. For example, the text message or TTS message for a 33*
number is sent in French. Use this parameter to explicitly control the language used.
*Note: Voice calls in English for bg-bg
, ee-et
, ga-ie
, lv-lv
, lt-lt
, mt-mt
, sk-sk
, sk-si
en-gb
, bg-bg
, cs-cz
, da-dk
, de-de
, ee-et
, el-gr
, es-es
, fi-fi
, fr-fr
, ga-ie
, hu-hu
, it-it
, lv-lv
, lt-lt
, mt-mt
, nl-nl
, pl-pl
, sk-sk
, sl-si
or sv-se
How long the generated verification code is valid for, in seconds. When you specify both pin_expiry
and next_event_wait
then pin_expiry
must be an integer multiple of next_event_wait
otherwise pin_expiry
is defaulted to equal next_event_wait. See changing the event timings.
Specifies the wait time in seconds between attempts to deliver the verification code.
Selects the predefined sequence of SMS and TTS (Text To Speech) actions to use in order to convey the PIN to your user. For example, an id of 1 identifies the workflow SMS - TTS - TTS. For a list of all workflows and their associated ids, please visit the developer portal.
Must be one of:1
, 2
, 3
, 4
, 5
, 6
or 7
The unique ID of the Verify request. You need this request_id
for the Verify check.
Indicates the outcome of the request; zero is success
The unique ID of the Verify request. This may be blank in an error situation
Code | Text | Description |
---|---|---|
0 | Success | The request was successfully accepted by Vonage. |
1 | Throttled | You are trying to send more than the maximum of 30 requests per second. |
2 | Your request is incomplete and missing the mandatory parameter $parameter
|
The stated parameter is missing. |
3 | Invalid value for parameter $parameter
|
Invalid value for parameter. If you see Facility not allowed in the error text, check that you are using the correct Base URL in your request. |
4 | Invalid credentials were provided | The supplied API key or secret in the request is either invalid or disabled. |
5 | Internal Error | An error occurred processing this request in the Cloud Communications Platform. |
6 | The Vonage platform was unable to process this message for the following reason: $reason
|
The request could not be routed. |
7 | The number you are trying to verify is blacklisted for verification. | |
8 | The api_key you supplied is for an account that has been barred from submitting messages. | |
9 | Partner quota exceeded | Your account does not have sufficient credit to process this request. |
10 | Concurrent verifications to the same number are not allowed | |
15 | The destination number is not in a supported network | The request has been rejected. Find out more about this error in the Knowledge Base |
20 | This account does not support the parameter: pin_code. | Only certain accounts have the ability to set the pin_code . Please contact your account manager for more information. |
29 | Non-Permitted Destination | Your Vonage account is still in demo mode. While in demo mode you must add target numbers to the approved list for your account. Add funds to your account to remove this limitation. |
0
, 1
, 2
, 3
, 4
, 5
, 6
, 7
, 8
, 9
, 10
, 15
, 20
or 29
If status
is non-zero, this explains the error encountered.
This endpoint does not support text/xml
POST /verify/psd2/:format HTTP/1.1
Host: api.nexmo.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 93
api_key=abcd1234&api_secret=Sup3rS3cr3t%21%21&number=447700900000&payee=Acme+Inc&amount=48.00
POST /verify/psd2/:format HTTP/1.1
Host: api.nexmo.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 176
api_key=abcd1234&api_secret=Sup3rS3cr3t%21%21&number=447700900000&country=GB&payee=Acme+Inc&amount=48.00&code_length=6&lg=es-es&pin_expiry=240&next_event_wait=120&workflow_id=4
{
"request_id": "abcdef0123456789abcdef0123456789",
"status": "0"
}
{
"request_id": "",
"status": "2",
"error_text": "Your request is incomplete and missing the mandatory parameter `number`"
}
This endpoint does not support text/xml