Vendo supports 3D Secure authentication, PIX, Crypto etc. when using the Gateway Payment API by redirecting to a verification step.

🚧

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 or Crypto. The flow is exactly the same for all of these transactions 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 the OTP Code 1234 (in the challenge form).

πŸ“˜

Other verification methods

3D Secure is the most important authentication process, but Vendo supports other payment methods and customer verification methods like PIX, Crypto, 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. User gets redirected to your payment page.

  2. You collect the credit card details in a form.

  3. You post a Payment API request with the credit card details and customer information etc.

    • 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 receive the API response back from Vendo which contains the URL to which the user needs to be redirected to in order to complete the 3DS process.

    • 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 the 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.
  8. You call the Payment API request that you posted in step #3 stripped from 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 declined.

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.

PlaceholderDescription
{REF}Will be replaced by the value that you passed in the external_references.transaction_reference field.
{EMAIL}Will be replaced by the value that you passed in the customer_details.email field
{STATUS}Will be replaced with verification transaction Vendo status (1/0). You may use it to decide to continue with the 2nd request (on 1) or to restart the flow (on 0)
{ERROR_CODE}If the verification transaction fails you will see Vendo error code here. Otherwise it will be left empty