Lorna Mitchell

Vonage Team Member

Lorna is a software engineer with an incurable blogging habit. She tries to tame words and code in equal measure.

[Read more]
< Tutorial />

Add Strong PSD2 Authentication to Your Application

Last updated on May 04, 2021

With more and more purchases made online, the dangers of fraud and unauthorized payments increase.

In response to this situation, a new standard for authenticating online payments was introduced in Europe called "Secure Customer Authentication," also known as PSD2 (Payment Services Directive version 2).

PSD2 introduces an additional security element to online payments. If you're doing transactions in Euro, then you can use our Verify API to help implement this extra element in your applications.

About Secure Customer Authentication

Secure Customer Authentication means making sure that more than one authentication type will be used for more substantial transaction amounts (the technical details and small print are also available). In short, transactions should include two from this list of three elements:

  • A password or PIN (something the user knows)
  • A fingerprint or face/eye scan (something the user is)
  • Information from a phone or hardware token (something the customer has)

Using the PSD2 feature in Verify API is a simple way to implement the third option from the list above.

How Verify API PSD2 Works

To authorize a payment, the API sends a code to the phone number recorded on the user's account.

Authorization can be by text message, telephone call, or usually a combination of both to reach the largest possible number of users. The user receives the pin along with information about the transaction: who they are paying and the amount of the payment.

Screenshot from phone with message: Your code 2393 is for payment to Acme Inc. in the amount of 12.34€. Valid for 5 minutes
Screenshot from phone with message: Your code 2393 is for payment to Acme Inc. in the amount of 12.34€. Valid for 5 minutes

The user then provides the pin that they received; this is sent back to the Verify API to check if the pin code is correct. If it is, the request is confirmed, and you can proceed with the payment.

Implement Verify API PSD2

We have examples in a few different tech stacks but to keep things very inclusive, these examples use cURL.

Vonage API Account

To complete this tutorial, you will need a Vonage API account. If you don’t have one already, you can sign up today and start building with free credit. Once you have an account, you can find your API Key and API Secret at the top of the Vonage API Dashboard.

Screenshot of new Meetings API session in progress
Start developing in minutes with free credits on us. No credit card required!

Send a PIN Code to Confirm a Payment

The first step is to send a code to the customer's phone to confirm their payment amount and who the payment is to. To ensure that the message did reach them, the message includes a PIN code.

The API reference for sending a PSD2 code is here for a full list of details and all the parameters available. For the simplest case, the cURL request looks like this:

curl -X POST "https://api.nexmo.com/verify/psd2/json" \
-d api_key=API_KEY -d api_secret=API_SECRET \
-d number=447700777000 -d payee="Acme, Inc" \
-d amount=12.34

Replace API_KEY and API_SECRET in the example above with your credentials, and also put in the phone number to send the PIN to; this should probably be your phone number while you are testing, and it should be in international format with no leading + symbol.

In this context, the PIN will be sent by SMS first. If the user doesn't supply the correct PIN within a few minutes, this will be followed up with an automated call to speak the information.

Having both approaches helps to reach more users successfully, but you can also choose the workflow that best fits your use case.

The request returns a request_id. Save this as you will need it in the next step!

Check the PIN Code

When the user submits the PIN code they received, you can confirm it is correct by calling the /check endpoint in the Vonage Verify API.

Check out the API reference documentation for the check endpoint for the precise details. Again code samples are available, and the cURL request looks like this:

curl -X POST "https://api.nexmo.com/verify/check/json" \
-d api_key=API_KEY -d api_secret=API_SECRET \
-d request_id=abcdef0123456789abcdef0123456789 -d code=1234

Again, replace API_KEY and API_SECRET with your credentials, and use the request_id returned in the previous step. The code parameter should be the pin code sent to the user.

If successful, the response will show a status of zero, and you can be confident that the user did authorize the payment.

Next Steps

In this post, we covered what the Secure Customer Authentication entails and an example of how to implement it in your applications. Here are some resources that you may find useful for your next step: