# Zuora

To integrate with Zuora, you must first set up and test your integration in the sandbox environment, and then move your integration to the production environment.

---

## Before you start

You must create a private key to configure the integration,

### Create a private API key

1. Sign in to the sandbox environment in the [Dashboard](https://identity-sandbox.checkout.com/).
2. Select _Developers_ in the left navigation bar and open the _Keys_ tab.
3. Select _Create a new key_.
4. Under _Type of key_, select _Secret API key_.
5. Give the API key a description. This will help you identify what it's used for.
6. Under _Scopes_, select _Default_.
7. Disable the _Allow any processing channel_ setting.
8. Select the processing channel you want to use for Zuora payments from the list.
9. Select _Create key_.
10. Copy your private API key securely. You'll need it to configure the plugin.

> **Note**
>
> For security, you cannot view the private API key again after you've left the _Create a new key_ page. Ensure you copy its value securely before you exit or close the window.

---

## Configure the gateway integration

In your Zuora dashboard:

1. Locate your username at the upper-right corner of the dashboard, and select it.
2. Go to _Settings_ > _Payments_ > _Set Up Payment Gateway_.
3. In the _Configure Gateway Instance_ tab, select _Checkout.com_ from the _Gateway Type_ dropdown.
4. Select _Create Gateway_.
5. Configure your gateway instance using the following options:
    - _Name_: Enter an alphanumeric value to describe the gateway.
    - _Use Gateway sandbox Environment_:  Enabling this option marks all transactions as tests and routes the transactions to the sandbox environment.
    - _Cards Accepted_: Select the cards you want to accept through this gateway. Ensure that your gateway's merchant account is also configured to accept the selected cards.
    - _Default Authorization Amount_: The amount used to validate credit cards. By default, this is set to `1`.
    - _Verify new payment method (optional)_: Enabling this option triggers a validation call for each new payment method.
        - For ACH, the verification is made through the ValidiFi account validation service. To verify new ACH payment methods, you must enable the _support for ValidiFi service_ option. <br>
        - For SEPA, you must send the source ID from Checkout.com in the `MandateID` field when creating the payment.
    - _Verify updated payment method (optional)_: Enabling this option triggers a validate call for each new payment method updated.
    - _Enable gateway reconciliation_: Enabling this option triggers a daily job to reconcile all payments processed through the gateway. <br>
    For more information, see [Zuora's Support for Gateway Reconciliation documentation](https://knowledgecenter.zuora.com/Zuora_Payments/Payment_gateway_integrations/Supported_payment_gateways/Checkout.com_payment_gateway_integration/A_Overview_of_Checkout.com_gateway_integration#Support_for_Gateway_Reconciliation).
    - _API Key_: Enter the private API key you generated in the Dashboard, prefixed with `Bearer`. For example, `Bearer <SECRET_KEY>`.
    - _Default Soft Descriptor (optional)_: Description shown after authorizing the payment. This field is required for all direct debit payment methods.
    - _3DS Challenge Indicator_: If 3DS2 is enabled in the _Payment Pages_ settings, this indicator is passed to the gateway. <br>
    For more information about this indicator, see [SCA compliance](https://www.checkout.com/docs/business-operations/ensure-regulatory-compliance/sca-compliance.md).
5. Select _Save Gateway Information_.

---

## Configure the payment methods

Checkout.com supports the following payment methods on Zuora:

* ACH direct debit
* Apple Pay
* Google Pay
* Card payments – along with the [Real-Time Account Updater](https://www.checkout.com/docs/payments/store-and-manage-credentials/update-stored-credentials.md) service
* [SEPA Direct Debit](https://www.checkout.com/docs/payments/add-payment-methods/sepa-direct-debit.md) – EUR only

To learn how to enable these payment methods, see Zuora Knowledge Center – [Supported payment methods](https://knowledgecenter.zuora.com/Zuora_Payments/Payment_gateway_integrations/Supported_payment_gateways/Checkout.com_payment_gateway_integration/A_Overview_of_Checkout.com_gateway_integration#Supported_payment_methods).

---

## Test your integration

In your [Zuora sandbox account](https://apisandbox.zuora.com/platform/webapp):

1. Go to _Customers_ > _Customer Accounts_.
2. Select _Add New Account_ and enter the required details.
3. In the _Payment Method_ field select _Credit Card_ .
4. Enter the following card details:
    - Number: `4242 4242 4242 4242`
    - Expiry date: any future date
    - CVV: `100`
5. Select _Save_ to create a customer.
6. Go to _Customers_ > _Customer Accounts_ > _Create payment_.

After creating the payment, you can find the Checkout.com payment ID in the _Reference ID_ field.

---

## Move your integration to the production environment

Contact Zuora to move your integration to the production environment.