Hosted 3-D Secure

Hosted 3-D Secure is available when using the API or Secure Fields, as long as 3-D Secure has been set up and turned on for at least one payment service. This integration equally supports Dynamic 3-D Secure which can be set up using Flow rules, allowing dynamic skipping or forcing of 3-D Secure based on anti-fraud decisions, cart items, or any other transaction data.

Usage

To use 3-D Secure via the API, set up 3-D Secure, turn it on for the enabled payment services, and pass a redirect_url when creating the transaction.

POST /transactions

{
  "amount": 1299,
  "currency": "AUD",
  "buyer_external_identifier": "user-1234",
  "payment_method": {
    "method": "card",
    "number": "4111111111111111",
    "expiration_date": "11/25",
    "security_code": "123",
    "redirect_url": "https://example.com/callback",
  }
}

With 3-D Secure turned on for a payment service, automatic detection occurs if it is required to get the buyer’s approval for a transaction. If it is required, the API returns 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.example.gr4vy.app/...",
    ...
  },
  ...
}

Treat the approval_url as an opaque value. Redirect the buyer to it exactly as returned, without parsing, rebuilding, or shortening it. The URL carries data for the issuer’s 3-D Secure steps, so its length varies by issuer and it can be long. Make sure anything that stores or forwards it doesn’t truncate it.

After the redirect, all the intricacies of 3-D Secure are handled. 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.

Gr4vy appends both a transaction ID and status to the redirect_url.

https://example.com/callback?gr4vy_transaction_id=123&gr4vy_transaction_status=capture_succeeded

Confirming the actual transaction status by fetching the updated transaction by its id is strongly recommended.

Buyers and billing details

To optimize 3-D Secure it is highly recommended to provide a buyer with billing details attached when making an API call. A buyer can be set up via the API or provided as an in-line guest buyer.

Features

For every transaction, the following steps are handled.

1. Detect if any Flow rule explicitly requires or skips 3-D Secure. For cards whose issuer mandates authentication, Gr4vy attempts 3-D Secure even when a rule skips it. See Issuer-mandated 3-D Secure.
2. Detect if the selected payment service for this transaction has 3-D Secure enabled
3. Detect if the card used in the transaction is enrolled for 3-D Secure
4. Handle the seamless frictionless 3-D Secure flow including the device finger printing once the user is redirected to the approval_url.
5. Handle the 3-D Secure challenge flow, where a buyer is directed to their bank to approve the transaction.