# 3D Secure (3DS)

3DS is a security protocol that helps prevent fraud in online credit and debit card transactions. 3D stands for the three domains that interact using the protocol: the merchant or acquirer domain, the issuer domain, and the interoperability domain.

## How 3DS works

When a customer makes a purchase online, the merchant's website sends a request to the cardholder's bank to authenticate the transaction.
The bank then sends a request to the cardholder to verify their identity.
The cardholder can verify their identity by entering a password, a one-time code, or using biometric authentication.

If the cardholder successfully authenticates the transaction, the bank sends a response back to the merchant, and the transaction is completed.
If the cardholder fails to authenticate the transaction, the transaction is declined.

## Benefits of 3DS

3DS provides the following benefits for merchants and cardholders:

- **Reduce fraud**: Prevent unauthorized transactions and reduce the risk of fraud.
- **Chargeback protection and liability**: Shift liability for chargebacks from the merchant to the cardholder's bank, reducing the financial risk for merchants.
- **Increase approval rates**: Increase approval rates for transactions by providing an additional layer of security.
- **Enhance customer trust**: Help build trust with customers by providing an extra layer of security for online transactions, and provides peace of mind when making online purchases.
- **Regulatory compliance**: Comply with regulations and industry standards for online transactions, reducing the risk of fines and penalties.
- **Global acceptance**: 3DS is widely accepted by banks and card networks around the world.
- **Reduced fraud-related costs**: Reduce fraud-related costs for merchants by preventing unauthorized transactions.


## Configure 3DS

This process describes how to configure 3DS on a payment gateway in Rebilly.

1. [Log in or sign up to Rebilly](https://app-sandbox.rebilly.com/).
2. In the left navigation bar, press .
3. In the **Configuration** section, press **Gateway accounts**.
4. In the list of gateway accounts, select a gateway account. 
If you are using the sandbox environment and have not set up a gateway account yet, select **TestProcessor**.
5. In the top right of the page, press **Edit gateway account**.
6. In the **Advanced configuration** section, turn on the **Advanced configuration** toggle.
7. In the **3D secure** section, select the **Activate 3D Secure** checkbox.
8. To enter 3D secure provider settings, select one of the following options:
Use test details  1. In the **Acquirer information** section, to load default test values that with the Rebilly 3DS provider ([3DSecure.io](https://www.3dsecure.io/)): press the **Load 3dsecure.io sandbox default values** button.
This provider can be used in both live and sandbox environments.
  2. In the **Merchant name** field, enter your merchant name.
  3. In the **Merchant country** dropdown, select a country.
  4. In the **Merchant URL** field, enter the URL of your website.
Example: `https://www.example.com`.
  5. In the **Transaction type** dropdown, select the type of transactions you want to process using 3DS.
The most commonly used transaction type is **Goods/Service purchase**.
  6. At the bottom of the page, press **Save gateway account**.
Use your merchant detailsUse this process to configure 3DS with your merchant information.
To use the Rebilly 3DS provider ([3DSecure.io](https://www.3dsecure.io/)), you must obtain the following merchant information from your payment gateway:
  - Acquirer Merchant Identification Number (MID) for both Visa and Mastercard.
  - Acquirer Bank Identification Number (BIN) for Visa (automatic enrollment).
  - Acquirer BIN for Mastercard (manual enrollment).
  - Merchant name.
  - Merchant country.
  - Merchant URL.

Mastercard enrollment must be initiated by the acquirer, and the acquirer must enroll the specific `acquirerBIN` and `acquirerMerchantID` into their system.
Enrollment is completed by the acquirer using the [Mastercard Connect ISSM tool](https://developer.mastercard.com/issm-merchant-enrollment/documentation/).
If required, Rebilly can provide all PCI DSS and PCI 3DS certification documentation.
For assistance, [contact Rebilly support](mailto:support@rebilly.com).
If you have your merchant information from your acquirer, in the **Acquirer information** section, complete the following:
  1. Depending on which payment cards you would like to use with 3DS, select from the following:
You must provide at least one acquirer merchant ID and BIN from the same provider.
Visa    1. In the **Merchant ID of the Visa acquirer** field, enter your acquirer merchant ID for Visa.
    2. In the **Bin of the Visa acquirer** field, enter your acquirer BIN for Visa.
Mastercard    1. In the **Merchant ID of the Mastercard acquirer** field, enter your acquirer merchant ID for Mastercard.
    2. In the **BIN of the Mastercard acquirer** field, enter your acquirer BIN for Mastercard.
American Express (AMEX)    1. In the **Merchant ID of the American Express acquirer** field, enter your acquirer merchant ID for American Express.
    2. In the **BIN of the American Express acquirer** field, enter your acquirer BIN for American Express.
Discover/Diners    1. In the **Merchant ID of the Discover/Diners acquirer** field, enter your acquirer merchant ID for Discover/Diners.
    2. In the **BIN of the Discover/Diners acquirer** field, enter your acquirer BIN for Discover/Diners.
JCB    1. In the **Merchant ID of the JCB acquirer** field, enter your acquirer merchant ID for JCB.
    2. In the **BIN of the JCB acquirer** field, enter your acquirer BIN for JCB.
  2. In the **Merchant name** field, enter your merchant name.
  3. In the **Merchant country** dropdown, select a country.
  4. In the **Merchant URL** field, enter the URL of your website.
Example: `https://www.example.com`.
  5. In the **Transaction type** dropdown, select the type of transactions you want to process using 3DS.
  6. Optionally, to decline transactions if the customer's bank does not support 3DS: Select the **Decline transactions if a payment card is not enrolled** checkbox.
  7. Optionally, to force 3DS authentication into challenge flow: Select the **Force challenge flow** checkbox.
  8. Optionally, if you are using 3DS for Visa payment cards: In the **Additional information** section, in the **Merchant category code** field, select your Merchant Category Code (MCC). 
The MCC is a four-digit number that identifies the type of business or service provided by the merchant.
The merchant category code field is required when using the Rebilly 3DS provider ([3DSecure.io](https://www.3dsecure.io/)) for Visa payment card brands.
  9. At the bottom of the page, press **Save gateway account**.
9. Optionally, to test your 3DS configuration:
Create a new customer and a test transaction  1. In the left navigation bar, press , then press **Customers**.
  2. In the top right of the page, press **Add customer**.
  3. Enter the test customers details, then press **Save customer**.
  4. In the right of the page, press , then press **Collect payment**.
  5. Enter the amount and add a description for the payment.
  6. Select the **Pay with Rebilly hosted payment form** option, and press **Submit**.
  7. Press **Copy URL** and open the URL in a browser.
  8. In the payment card number field, enter 4111111111111111.
Use a future expiration date, and any valid CVV.
  9. Press **Continue**, then press **Confirm**.

In the response, an `approvalUrl` value is returned.
At the URL, simulate the different outcomes of the challenge flow in a 3DSecure.io sandbox environment.
To test different 3DS flows, use the last four digits from 3dsecure.io to generate a card number which passes Luhn check.
For more information, see [3DS browser tests](https://docs.3dsecure.io/3dsv2/sandbox.html#browser-tests).
Alternatively, select from the following predefined cards numbers to test 3DS outcomes:
| Card brand | Number | Outcome |
|  --- | --- | --- |
| Visa | 4111111111111111 | Manual challenge |
| Mastercard | 5555555555554444 | Frictionless flow, authenticated |
| Visa | 4000000000000002 | Frictionless flow, not authenticated |
| Mastercard | 5105105105105100 | Frictionless flow, not authenticated |

For more information on how to test 3DS, see [Test a 3DS challenge flow](/docs/tutorials/test-transactions#test-a-3ds-challenge-flow) and [Test a generic offsite approval flow](/docs/tutorials/test-transactions#test-a-generic-offsite-approval-flow).


## 3DS flow

This process describes the flow of a 3DS transaction between a merchant, a cardholder, and the cardholder's bank:

1. **Authentication request**: The merchant sends an authentication request to the cardholder's bank.
2. **Cardholder authentication**: The cardholder authenticates the transaction using a password, one-time code, or biometric authentication.
3. **Transaction response**: The bank sends a response back to the merchant, indicating whether the transaction was authenticated or declined.
4. **Transaction completion**: If the transaction is authenticated, the transaction is completed.
If the transaction is declined, the cardholder is prompted to try again or use a different payment method.


## 3DS internal flow

This process describes the internal flow between a payment gateway that is using 3DS and Rebilly.

1. A transaction is created and 3DS is enabled on the selected payment gateway.
Rebilly returns the `approvalUrl` and the transaction with a `status` of `waiting-approval` and a `result` of `unknown`.
2. Rebilly detects when the customer is redirected to the `approvalUrl`.
When this occurs, the transaction `status` is set to `offsite` and the `result` is set to `unknown`.
Rebilly does not redirect the customer to the`approvalUrl`, that must be completed by whomever is calling the API.
3. After a successful 3DS flow that triggers the call to the payment gateway, the customer is redirected back to Rebilly.
4. Rebilly receives the response from the payment gateway.
The transaction `status` is set to `completed` and `result` is set to `approved`, or `declined`.
5. The customer is redirected back to the `redirectUrl`.


To view all transaction result and status values, [status](/docs/dev-docs/api/transactions/posttransaction#transactions/posttransaction/t=response&c=201&path=status) and [result](/docs/dev-docs/api/transactions/posttransaction#transactions/posttransaction/t=response&c=201&path=result).

## Test 3DS

To verify your 3DS configuration is working correctly, see [Test a 3DS challenge flow](/docs/tutorials/test-transactions#test-a-3ds-challenge-flow) and [Test a generic offsite approval flow](/docs/tutorials/test-transactions#test-a-generic-offsite-approval-flow).