# 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. Clear the **Use 3DS for merchant-initiated transactions** checkbox. This option is used for transactions initiated by the merchant, such as recurring payments. It is not applicable for the test information you entered in this section.
  7. At the bottom of the screen, 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. Clear the **Use 3DS for merchant-initiated transactions** checkbox. 
This option is for merchant-initiated transactions, such as recurring payments. For more information about 3DS and merchant-initiated transactions, [contact Support](/contact/).
  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 screen, 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 screen, press **Add customer**.
  3. Enter the test customers details, then press **Save customer**.
  4. In the right of the screen, 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).