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.

Verification and Authentication in Gateway Payment API

📘

2-Step Transactions

To support 2-step transactions, such as 3D Secure, PIX, Pay by Bank, or Crypto, follow the flow outlined below. The process is identical for all these payment methods, so there's no need to account for differences between them.

The Gateway Payment API supports transactions that require the end user to verify their identity, such as confirming they are the legitimate account holder or verifying they are not a bot.

When submitting a payment request, the response may return a transaction status of "2", indicating that the transaction is pending and requires further verification, authorization, or authentication.

You will need to redirect the user to the URL provided in the results.verification_url response parameter. Here, they will complete the required challenge, such as 3D Secure authentication, a CAPTCHA, a QR code for PIX payment, or a payment authorization for Pay by Bank.

After completing the verification process, the user will be redirected back to the Success URL configured in your Backoffice.

Next, you must send a second API request using the same payment details along with the verification_id provided in the initial response. The final API response will confirm whether the transaction was successful. If the transaction fails, the response will prompt you to redirect the user again to restart the verification process.

In some cases, transactions do not require a second API request. Instead, you will receive a transaction postback notification immediately after the user authorizes and approves the payment. However, you can still send the second API request if needed, and the Gateway API will return the final transaction status.

🚧

Avoid Relying on Browser Redirections

Redirecting the user to your Success URL does not guarantee that the transaction or authentication was successful. Instead, it’s recommended to rely on the transaction postback notification for accurate confirmation of the transaction status.

👍

Testing 3D Secure Verification Process

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

📘

Timeouts

If the customer is not redirected back to your site after the verification step, wait for the postback notifications. If no postback is received, retry the original payment request.

📘

3D Secure and Other Verification Methods

While 3D Secure is the most widely used authentication process, Vendo also supports other payment and customer verification methods, including PIX, Crypto, Pay by Bank, CAPTCHA, and Phone Verification. The implementation flow is identical across all these methods, so you only need to implement it once.

2-Step Transaction Flow

👍

Simplified for Your Convenience!

This flow is purposely designed to minimize the implementation effort on your end. We handle all the complex processes, so you don’t have to. Just follow these simple steps, and we’ll take care of the rest!

1. The user is redirected to your payment page.
2. You collect the customer’s information and payment details through a form.
3. You submit a Payment API request using the collected data and any other necessary information.
   1. Since you'll need to resubmit this request later, ensure that all required data is securely stored in the session or database (except for credit card information, which cannot be stored due to PCI compliance rules).
4. You receive a response from Vendo’s API, which includes a URL for the user to complete the verification step, such as 3D Secure authentication, PIX payment via QR code, Crypto account selection, or Pay by Bank account selection.
   1. The response will contain status=2, indicating that "The transaction requires verification." You must redirect the user to the URL specified in result->verification_url.
   2. Additionally, the response provides a verification_id that you can store to avoid the need to save sensitive credit card information.
5. Redirect the user to the provided verification_url.
6. The user proceeds with the verification process (e.g., authentication and authorization).
   1. Note: The flow continues regardless of whether this step succeeds or fails.
   2. You cannot determine the final verification status until the original payment request is reposted or a postback notification is received.
7. After completing the verification, the user is redirected back to your site.
   1. The redirection uses the Success URL configured for your site in Vendo’s back office.
   2. At this point, the verification may have been accepted or rejected.
8. You must now resubmit the original Payment API request from step #3.
   1. Remove the customer_details section.
   2. In the payment_details section, include only the verification_id from step #4.
   3. Vendo will then verify whether the authentication was successful.

      📘

      You may skip the second confirmation request for Pay by Bank, Crypto, and PIX if it’s more convenient.

      Inform your account manager or MCS if you prefer payments to be completed as soon as the customer is charged.

9. You receive the final transaction status from Vendo’s API:
   1. Status = 1: The transaction was successfully processed.
   2. Status = 0: The transaction was rejected.
   3. If you want the user to retry the verification process, you’ll need to repost the Payment API request from step #3.
      1. This time, include the customer_details section.
      2. In the payment_details section, either pass the credit card details or use the payment_details_token received 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.