3D Secure and other 2-step payment methods

🚧

Strong Customer Authentication

Strong Customer Authentication is mandatory for many transactions and can be provided by 3D Secure.
You need to understand and implement this flow to support SCA.

Transactions that need authentication, authorization or verification

📘

2-step transactions

You need to support the flow described below to support 2-step transactions like 3D Secure, PIX, Pay by Bank or Crypto. The flow is exactly the same for all of these payment methods and you don't need to worry about the differences between them.

The Gateway Payment API supports transactions where it is required that the end user proves that they are f.ex. the genuine account holder or that they are simply not a robot.

When performing a Payment request, the response may indicate that the status of the transaction is "2", i.e. the transaction is pending because it needs additional verification, authorization or authentication.

You must redirect the end user to the URL provided in the results.verification_url response parameter where they will receive the necessary challenge, e.g. 3D Secure or Captcha or a QR code to pay with PIX. At the end of the verification process the user will be redirected back to the Success URL configured in the Backoffice for your site.
However, this does not guarantee that the transaction or authentication was successful!

You must then repeat the original Payment request with the same parameters (or use the payment details token received in the first request), whereafter you will get a response letting you know if the transaction was successful. If the transaction was not successful, the response will once again tell you to initiate the verification process by redirecting the end user.

Timeouts: If the customer is not redirected back to your shop after the verification step, you should try the original Payment request again after waiting for 30 minutes. It's possible that the payment was successful but that he closed his browser before being redirected. By repeating the Payment request after 30 minutes you will know if the order was successfully paid and you can send the customer a confirmation email so he is aware.

To test the 3D Secure verification process, use the credit card number 4000012892688323 and click on "I accept" to simulate successful 3D Secure authentication and authorization of the transaction.

📘

Other verification methods

3D Secure is the most important authentication process, but Vendo supports other payment methods and customer verification methods like PIX, Crypto, Pay by Bank, Captcha, Phone Verification. The flow is exactly the same and needs only to be implemented once.

This is the flow of a 2-step transaction

👍

Note: Keeping it simple!

This flow is intentionally designed to require the smallest implementation footprint on your side - in other words: we take care of all the complexity so you don't have to, as long as you follow these simple steps!

1. The user gets redirected to your payment page.

2. You collect the customer information and payment details in a form.

3. You submit a Payment API request with the gathered information and any other necessary data.

   • You will need to repeat this request again later, so make sure you save all the info you need in the session or database (except credit card info which is not allowed to be stored in the database under PCI rules).

4. You received the API response from Vendo, containing the URL to redirect the user to complete the Verification step, such as 3D Secure authentication, QR code for PIX payment, Crypto account selection, or Account Selection to Pay by Bank.

   • The response contains status=2 which means "The transaction needs verification". You need to redirect the user to the url specified in result->verification_url.
   • The response contains a verification_id which you can save so you don't have to save the credit card information.

   • 🚧

     DEPRECATED

     The response also contains a payment_details_token which you can save so you don't have to save the credit card information

5. You redirect the user to the verification_url.

6. The user attempts to authenticate and authorize the transaction.

   • Note: The flow must continue, regardless of whether this step was successful or not!
   • It's not possible to confirm the status of the verification until the payment request is reposted!

7. The user is redirected back from the authentication page to your shop

   • We use the Success URL that's configured for your site in Vendo's backoffice.
   • At this point, the verification could be either accepted or rejected.

8. You need to call the Payment API request that you posted in step #3 again.

   • Remove customer_details section.
   • In the payment_details section use only one field - verification_id that you got in step #4

   • 🚧

     DEPRECATED

     You can either use the credit card details or the payment_details_token that you got in step #4

   • Vendo checks if the verification was successful

9. You receive the final transaction status from Vendo's API response

   • If the status is 1 the transaction was successfully processed
   • If the status is 0 the transaction was rejected.
     • If you want the user to try the verification process one more time, you need to call the Payment API request that you posted in step #3 again.
       • The customer_details section is required
       • In the payment_details section you can either pass the credit card details or the payment_details_token that you got in step #4

Success URL - Redirecting users back to you

We can configure a success url with placeholders which will be replaced by real transaction data before the user gets redirected back to you.

For example, if the success url is set to https://www.yoursite.com/vendo/success_url.php?reference={REF}&email={EMAIL} then the user will be redirected back to https://www.yoursite.com/vendo/success_url.php?reference=mytxref123&email=theusermeail%40example.com after the verification step is completed (successful or not).

The {REF} placeholder will be replaced with the value that you passed in the Payment API request parameter external_references.transaction_reference, e.g. mytxref123 and the {EMAIL} placeholder will be replaced by the value passed in customer_details.email, e.g. [email protected].

Placeholders

You can use the placeholders listed in the table below in your Success URL, Vendo's platform will replace them with actual transaction data.