Auto 3-D Secure Step-up

What is Auto 3-D Secure Step-up?

Auto 3-D Secure (3DS) Step-up is a BR-DGE feature that is designed to maximise your payment approval rates by intelligently handling 3-D Secure "soft declines".

The Auto 3-D Secure Step-up feature is one automated flow and works in the following way:

First attempt: BR-DGE first attempts to process the payment.
Automatic re-attempt (Step-up to 3DS): If the card issuer returns a soft decline, BR-DGE captures the decline (code 4278) and immediately re-triggers a second payment attempt, this time processing the payment with threeDSecureRequired set to TRUE.

This automated "step-up" ensures the transaction doesn't simply fail. Instead, it transitions to the necessary authentication protocol, giving the cardholder the chance to authenticate and complete the purchase.

How to use Auto 3-D Secure Step up?

This functionality is available on both the POST /v1/orders and /v1/payments API, as a boolean flag under the threeDSecureOptions object.

API Field Name	Type	Description
`threeDSecureOptions.automaticallyStepUp`	boolean	Setting this to True automatically retries payments with 3DS enabled when the response code is `4278 Customer authentication is required`.

Example API Requests

POST /v1/payments

{
  "amount": 1600,
  "channel": "web",
  "currencyCode": "GBP",
  "customerOrderCode": "123456",
  "customerFirstName": "John",
  "customerLastName": "Doe",
  "customerIpAddress": "123.100.100.200",
  "customerEmail": "[email protected]",
  "browserData": {
    "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
    "colorDepth": "24",
    "javaEnabled": false,
    "language": "en-GB",
    "screenHeight": 844,
    "screenWidth": 390,
    "timeZone": 0,
    "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148 YourAppName/1.0"
  },
  "paymentInstrument": {
      "type": "card",
      "nameOnCard": "John Doe",
      "pan": "4444 3333 2222 1111",
      "expiryDate": "03-30",
      "cv2": "123",
      "tokenize": true
  },
  // ... other transaction details ...
  "threeDSecureOptions": {
      "automaticallyStepUp": true
  }
}

POST /v1/orders

{
    "amount": 15000,
    "merchantTransactionId": "{{$guid}}",
    "channel": "ios",
    "currencyCode": "GBP",
    "customerEmail": "[email protected]",
    "customerFirstName": "customerFirstName",
    "customerIpAddress": "1.1.1.2",
    "customerLastName": "customerLastName",
    "customerOrderCode": "{{$guid}}",
    "customerPhoneNumber": "+44 456 1113000",
    "customerSessionId": "123456",
    "orderDescription": "Taxi fare",
    "returnUrl": "https://example.com",
    "threeDSecureOptions": {
        "automaticallyStepUp": true
    }
}

Check out our API Reference for a full overview of the API.

When you set automaticallyStepUp to true, you can expect one of the following outcomes:

Approved on first attempt (No 3DS): The payment is approved immediately without any action needed from the cardholder. Your system receives a final approval response.
3-D Secure required: BR-DGE re-attempts the payment with 3DS and drops you into the BR-DGE 3DS flow. Refer here for more information on BR-DGE’s 3-D Secure flow.

When to use Auto 3-D Secure Step-up?

Scenario	Recommendation	Rationale
Using BR-DGE’s Hosted Payments Page.	✅ – Use it	If you include auto 3DS step up on your orders, then you do not need to recreate another order in the event of a 4278 response from BR-DGE.
Using a single-use token to make payments	✅ – Use it	BR-DGE’s single token only works for a single payment attempt. In the event of a 4278 response code, you will need to request the card details again to create another single use token
SCA/PSD2 Context	✅ – Use it	For payments in regions like the EEA/UK, the bank may not always require SCA for low-value or low-risk transactions. This feature tries the non-3DS path first, only stepping up when SCA is strictly mandated by the issuer.
Merchant Initiated Transactions	❌ – Avoid it	Merchant Initiated Transaction do not require 3-D Secure.
MOTO payments	❌ – Avoid it	MOTO payments do not require 3DS, given the nature of MOTO payments and their lack of cardholder interaction.