Skip to main content
Version: Beta

Hosted 3-D Secure

Universal 3-D Secure is also available without Gr4vy Embed as long as any payment service has been set up for 3-D Secure.


All you need to do to use 3-D Secure via the API is to set up 3-D Secure on any of the enabled payment services and pass a redirect_url when creating the transaction.

curl -i -X POST "https://api.{gr4vyId}" \
-H "Authorization: Bearer [JWT_TOKEN]" \
-H "Content-Type: application/json" \
-d '{
"amount": 1299,
"currency": "USD",
"payment_method": {
"method": "card",
"number": "4111111111111111",
"expiration_date": "11/25",
"security_code": "123",
"redirect_url": "",
"buyer_external_identifier": "user-1234",

With 3-D Secure configured for a payment service, we will automatically detect if it is required to get the buyer's approval for a transaction. If it is required the API will return a transaction with the status buyer_approval_pending and an approval_url that the buyer can be sent to.

"type": "transaction",
"id": "869df4fc-a3db-43db-806a-14464d9e6920",
"status": "buyer_approval_pending",
"payment_method": {
"approval_url": "https://embed.{gr4vyId}",

You can then redirect the buyer to the approval_url and Gr4vy will handle all the intricacies of 3-D Secure. Once the buyer has approved (or rejected) the transaction the browser is redirected back to the redirect_url that was set when the transaction was created.

The redirect_url will be appended with both a transaction ID and status.

We strongly recommend confirming the actual transaction status by fetching the updated transaction by its id.

Buyers & Billing Details

To optimize 3-D Secure it is highly recommended to provide a buyer with billing details attached to Gr4vy Embed.

A buyer can be set up via our POST /buyers API. The buyer can then be attached to Gr4vy Embed by using the buyerId or buyerExternalIdentifier property. The buyer's name, email address, and billing address will be used to help reduce buyers being requested to complete a 3-D Secure challenge.


For every transaction Gr4vy will handle the following steps.

  1. Detect if the selected payment service for this transaction has 3-D Secure enabled
  2. Detect if the card used in the transaction is enrolled for 3-D Secure
  3. Handle the seemless frictionless 3-D Secure flow including the device finger printing once the user is redirect to the approval_url.
  4. Handle the 3-D Secure challenge flow, where a buyer is directed to their bank to approve the transaction.