Cash Developer Portal
Crear cuenta

Support

Whatsapp




3D Secure

3DS is a technical standard that adds a layer of security to online credit and debit card transactions. 3D stands for “three domains.” The first is the card issuer, the second is the retailer receiving the payment, and the third is the 3DS infrastructure platform that acts as a secure go-between for the consumer and the retailer.

How does it works?

step 1

3D # 1

Card information collection

The card holder enters their unique credit or debit card data

step 2

3D # 1

Redirection to providers 3D secure pages

If 3D Secure entollment is confirmed the client is then redirected to a 3D Secure page served by the card provider.

step 3

3D # 1

Additional security authentication

On the provider’s website, the client will be asked to enter their unique password or a one-time authentication code wich will be emailed to their confirmed email adress or sent to their confirmed number.

step 4

3D # 1

Redirection to merchant’s website

If the cardholder authentication went successfully the cardholder is then redirected back to a merchant’s website for payment confirmation.

step 5

3D # 1

Payment confirmation page

Once back on the merchant’s site, the customer will recieve confirmation of a successful payment.

How to implement 3DS?

  1. First, you need to login into the merchant portal using your credentials.
    2. 3D # 1
  2. From the menu, navigate and select the Developer menu.
    3. 3D # 1
  3. Enter the URL where the customer is going to be redirected if the 3DS Challenge is complete.
    4. 3D # 1
  4. The 3D Secure redirection URL is going to appear in the list here, remember that you can change it at any time.
    5. 3D # 1
  5. Now you can create a Charge using the Transaction endpoint.
  6. If there is the need for the customer to complete the 3DS Challenge, you will get a 400 response, with the pending status, and the detail.code indicating action_required. In the detail.additional_details.action will be set to 3ds_authenticateindicating that the customer needs to be authenticated using 3DS and detail.additional_details.redirect_url points to the URL that the customer should be redirected to authenticate
    7. 3D # 1
  7. Once the authentication is complete the customer is redirected to the URL set in step 3. The hola.cash Transaction ID is also provided as the query parameter TID

    8. transaction_id: str = request.query_params.get("TID", None)

    3D # 1
  8. You can use the Transaction ID to check the status of the transaction by using the get transaction details.
  9. When the 3DS authentication is successful, a webhook with the charge succeeded is sent to the defined webhook URL (for more info check the Webhook Tutorial), if the 3DS Authentication fails, then a webhook with the charge "failed"is sent. You can always use these webhooks to trigger specific workflows in your app.

How do I test 3DS transactions?

    Before moving into a productive environment it is important to test funcionality. In order to enable this, we have a Sandbox environment in the widget & API from Hola Cash. To access this env you need to use your Sandbox keys when calling the api or setting up the widget. In 3DS transactions the Sandbox environment has some details. Before starting, in this other section of the docs you can find testing cards for this procedure.

    If you take a look at step 6 for the 3DS implementation we can see that the api response error contains a url. This url is a redirect url for the users, when they are redirected into this page they'll be able to complete their authentication. In sandbox, this url will redirect users to a testing 3DS environment, here you'll be able to visually choose the flow of the transaction. By clicking any of the two buttons the preconfigured redirect urls from the portal are generated, then an event will be triggered to any configured webhook url

    Remember, to trigger a 3DS authentication you have to send the exact amount mentioned in the testing cards section.

    You can quickly test the behavior via Curl, remember to replace the call with your own credentials.

    Token Creation

    curl --location --request POST 'https://sandbox.api.holacash.mx/v2/tokenization/payment_token' --header 'X-Api-Client-Key: <PASTE YOUR SECRET API KEY>' --header 'X-Cash-Anti-Fraud-Metadata: ewogICAgImlwX2FkZHJlc3MiOiIxMjMuMTIzLjEyMy4xMjMiLAogICAgImRldmljZV9pZCIgOiAiMTIzNDU2MTIzNDU2IiwKICAgICJ1c2VyX3RpbWV6b25lIiA6IiswMzozNCIsCiAgICAidXJsX2RvbWFpbl9uYW1lIiA6ImhvbGFjYXNoLm14IiwKICAgICJicm93c2VyX3ZlcnNpb24iIDoiMTIzIiwKICAgICJicm93c2VyX25hbWUiIDoiTW96aWxsYSIsCiAgICAiYnJvd3Nlcl90aW1lem9uZSIgOiJQU1QiLAogICAgInNjcmVlbl9yZXNvbHV0aW9uX3dpZHRoIiA6IjEyMyIsCiAgICAic2NyZWVuX3Jlc29sdXRpb25faGVpZ2h0IiA6IjEyMyIsCiAgICAid2luZG93X3Bvc2l0aW9uX3giIDoiMTIzIiwKICAgICJ3aW5kb3dfcG9zaXRpb25feSIgOiIxMjMiLAogICAgImNvbG9yX2RlcHRoIiA6IjEyMyIKfQ==' --header 'Content-Type: application/json' --data-raw '{ "credential": { "payment_method": { "method": "credit_or_debit_card" }, "credit_or_debit_card": { "card_number": "4000000000003063", "expiration_month": "12", "expiration_year": "2034", "card_validation_code": "123" } }, "consumer_details": { "contact": { "email": "richa@abc.com" }, "name": { "first_name": "Test", "second_first_name": "Hola", "first_last_name": "Cash", "second_last_name": "User" } } }'

    Charge creation (replace payment_token)

    curl --location --request POST 'https://sandbox.api.holacash.mx/v2/transaction/charge' --header 'X-Api-Client-Key: <PASTE YOUR PUBLIC API KEY>' --header 'X-Cash-Anti-Fraud-Metadata: ewogICAgImlwX2FkZHJlc3MiOiIxMjMuMTIzLjEyMy4xMjMiLAogICAgImRldmljZV9pZCIgOiAiMTIzNDU2MTIzNDU2IiwKICAgICJ1c2VyX3RpbWV6b25lIiA6IiswMzozNCIsCiAgICAidXJsX2RvbWFpbl9uYW1lIiA6ImhvbGFjYXNoLm14IiwKICAgICJicm93c2VyX3ZlcnNpb24iIDoiMTIzIiwKICAgICJicm93c2VyX25hbWUiIDoiTW96aWxsYSIsCiAgICAiYnJvd3Nlcl90aW1lem9uZSIgOiJQU1QiLAogICAgInNjcmVlbl9yZXNvbHV0aW9uX3dpZHRoIiA6IjEyMyIsCiAgICAic2NyZWVuX3Jlc29sdXRpb25faGVpZ2h0IiA6IjEyMyIsCiAgICAid2luZG93X3Bvc2l0aW9uX3giIDoiMTIzIiwKICAgICJ3aW5kb3dfcG9zaXRpb25feSIgOiIxMjMiLAogICAgImNvbG9yX2RlcHRoIiA6IjEyMyIKfQ==' --header 'Content-Type: application/json' --data-raw '{ "description": "This is a test description", "amount_details": { "amount": 5070, "currency_code": "MXN" }, "payment_detail": { "credentials": { "payment_method": { "method": "pay_with_holacash_payment_token" }, "holacash_payment_token": { "payment_token": <PASTE YOUR PREVIOUSLY CREATED TOKEN> } } }, "consumer_details": { "external_consumer_id": "your_consumer_id", "contact": { "id": "1234", "email": "abc@abc.com" }, "name": { "first_name": "Snoop", "second_first_name": "the", "first_last_name": "Doggy", "second_last_name": "Dog" } }, "processing_instructions": { "auto_capture": false } }'