Implement PSD2 Compliance for Payments

This page walks you step-by-step through how to implement payment verification with the TeleSign SMS Verify API that complies with the European Union’s Revised Payment Services Directive (PSD2). This includes the directive’s Strong Customer Authentication (SCA) requirement; our API helps you comply with the “Possession” part of this requirement.

Keep the reference pages POST /v1/verify/sms and GET /v1/verify/{reference_id} open in another window while you work on these steps.

You can also skip straight to the Python sample code in GitHub.

Note:

This guide assumes that TeleSign is generating the verification code for you. If you prefer to generate your own code, take a look also at Verify By SMS With Your Own Code and adapt these steps accordingly.

Before You Begin

  • (Optional) Contact our Customer Support Team to configure any of these optional features:
    • Validity Period: The time duration in minutes after which a verification code expires.
    • Max Attempts: The number of times an end user can submit potential matches for a specific verification code. If this number is five, for example, an end user’s sixth submission is rejected, even if it matches the original code.

Step 1: Send the SMS

  1. Send a POST /verify/sms request to the SMS Verify API. Include the following param values:
Parameter Value Description Required?
phone_number Digits without spaces or special characters. The end user’s phone number you want to send a message to, beginning with the country/dialing code. yes
transaction_amount A currency and amount.

Example: $95
Replaces the $$AMOUNT$$ variable in the message template. Specifies the currency and amount for the payment that the end user is approving. yes
transaction_payee Text Replaces the $$PAYEE$$ variable in the message template. Specifies the entity that the end user is approving a payment to. yes
template Text with variables. Text that overrides the contents of the predefined message templates. Include the $$CODE$$ variable to have the verification code automatically inserted. Include the $$AMOUNT$$ and $$PAYEE$$ variables to have those payment details from your other params automatically inserted. no
NOTE:

You can use one of TeleSign’s non-English (US) message templates by including the optional language parameter. To see a full list of languages for which we have PSD2/SCA templates, see the section Supported Languages.

SMS Verify Request
HTTPS
POST /v1/verify/sms HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck=
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: rest-ww.telesign.com

phone_number=15558675309
&transaction_amount=$95
&transaction_payee=Viatu
&template=To confirm your payment to $$PAYEE$$ in the amount of $$AMOUNT$$ your code is $$CODE$$. Thank you for shopping with us.
Note:

We used €95 as the example value here because PSD2’s threshold for using SCA is €30. You can choose either to perform SCA for all transactions or check whether the amount is greater than €30 first.

  1. The service then sends an SMS message, replacing the $$CODE$$ variable in the message template with a verification code, and the $$PAYEE$$ and $$AMOUNT$$ variables with your provided payment details. You include the payee and amount to comply with PSD2’s requirement for dynamic linking.
Generated Message
Generated Message
  1. Save the value of the property reference_id from the response. You will need it to complete the verification flow.
  2. The status.code and status.description properties in the response indicate the preliminary delivery status of the SMS.
SMS Verify Response
HTTPS
HTTP/1.1 200 OK
Content-Type: application/json

{
  "reference_id": "0123456789ABCDEF0123456789ABCDEF",
  "sub_resource": "sms",
  "errors": [],
  "status": {
    "updated_on": "2015-10-03T14:51:28.709526Z",
    "code": 290,
    "description": "Message in progress"
  },
  "verify": {
    "code_state": "UNKNOWN",
    "code_entered": ""
  },
  "additional_info": {
    "message_parts_count": 1
  }
}
NOTE:

The status.code property gives you status of delivery to the destination carrier, not necessarily all the way to the end-user.

Step 2: Complete Verification and Get Delivery Status

Once your end-user has submitted a potential code through your application, complete the verification flow with a second API call.

  1. Send a GET /verify/{reference_id} request.
    • Include the end-user’s potential code in the verify_code query parameter.
    • Include the reference_id for the transaction in the reference_id path parameter.
Get Status Request
HTTPS
GET /v1/verify/0123456789ABCDEF0123456789ABCDEF?verify_code=57244 HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck=
Host: rest-ww.telesign.com
  1. In the response, if the value of the verify.code_state property is VALID, the verification completed successfully.
  2. The status.code and status.description properties in the payload of that response indicate the delivery status all the way to the end-user.
Get Status Response
HTTPS
HTTP/1.1 200 OK
Content-Type: application/json

{
  "reference_id": "ABCDEF0123456789ABCDEF0123456789",
  "sub_resource": "sms",
  "errors": [],
  "status": {
    "updated_on": "2015-04-17T22:26:43.784963Z",
    "code": 201,
    "description": "Message is read"
  },
  "verify": {
    "code_state": "VALID",
    "code_entered": ""
  },
  "additional_info": {
    "code_entered": null,
    "message_parts_count": 1
  }
}
  1. If the value of the verify.code_state property is EXPIRED or MAX_ATTEMPTS_EXCEEDED, the verification code is no longer matchable by your end user. If you still want to give them the opportunity to verify, make a new SMS Verify request to send them a new verification code.

The complete Python sample code for this how-to guide can be found on GitHub.