Last updated

Set up a payment gateway

This topic describes how to add and configure a payment gateway in Rebilly.

If you are experimenting with the product in the sandbox environment, a test payment gateway called TestProcessor is configured for all Rebilly accounts.

To complete this process, you must have payment gateway account credentials.

  1. Log in or sign up to Rebilly.

  2. Select an environment: In the left navigation bar, in the bottom corner, click your initials and then select Sandbox or Live environment.

  3. In the left navigation bar, click Settings .

  4. In the Configuration section, click Gateway accounts.

  5. Click Add gateway account.

  6. In the list of gateways, select a gateway account.
    Use the Search by name field to search for gateways. If the gateway that you require is not listed, Rebilly will integrate it free of charge. For more information, see Gateway integration requests.

  7. In the Gateway account ID field, enter a unique alphanumeric value. Use a value that is recognizable in your reports. Gateway account IDs are used in other configuration screens, and are also how accounts are referenced within the Rebilly API.

  8. In the Payment methods section, select the payment methods you want active on this payment gateway.

  9. In the Accepted currencies section, click in the Select currencies field and add one or more currencies.

  10. Optionally, to define the setup instruction for new payment instruments:
    In the Setup instruction section, click the Instruction dropdown, and select from the following:

    • Do nothing: Do not use any setup instruction for new payment instruments.
    • Authorize: Verify that the payment instrument is valid by placing a hold on the cardholder's account for the authorized amount. An authorization response code is later used to capture the authorized funds.
    • Authorize and void: Verify that the payment instrument is valid by charging a small amount to the payment instrument. The amount immediately voided.
    • Strong Customer Authentication (SCA): Redirect the customer to the website of the issuing back to authenticate the customer. SCA requires the cardholder's interaction. For more information, see Configure 3D Secure (3DS) in the steps below.
  11. Optionally, to configure how the gateway manages payout requests:

    1. In the Ready to payout instructions section, turn on the Activate this gateway account for payouts toggle.
    2. Select one of the following options:
      • Covered payout: Use this gateway if it previously processed a payment for the same, or a greater, amount.
      • Approved payments: Use this gateway if it previously processed a payment for the same amount. The customer must have a previously approved transaction, in the same currency, on this gateway.
      • All payments: Use this gateway for any amount.
        For more information, see Manage payout requests.
  12. Optionally, to configure advanced gateway settings, select from the following:

    Configure card statement descriptions

    Use this process to assign a name to display on the cardholder's monthly statement, or to use a dynamic descriptor.

    A descriptor is the text that is displayed on the cardholder's billing statement. It identifies the source of a credit or debit card transaction. A dynamic descriptor can be modified on a per-transaction basis.

    1. In the Advanced configuration section, turn on the Advanced configuration toggle.
    2. In Card statement description, select one of the following: - To assign a name to display on the cardholder's monthly statement: In the Card statement description section, in the Descriptor field, enter the name to display on the monthly statement. In the City field, enter a city. - To assign a descriptor dynamically: Select the Dynamic descriptor checkbox.
    Configure custom fields

    Use this process to add custom fields to a payment gateway account. Custom fields extend a resource schema to include custom data that is not provided as a common field. For more information, see Custom fields.

    If you have not created any custom fields this section will be empty. For more information, see Create custom fields.

    1. In the Advanced configuration section, turn on the Advanced configuration toggle.
    2. In the Custom fields section, complete the required fields.
    Configure Dynamic Currency Conversion (DCC)

    Use this to process to activate DCC on a payment gateway account. DCC detects when a customer is attempting to pay in a currency that is not native to their region, and presents an offer to pay in their native currency at a small markup. For more information, see Dynamic currency conversion.

    1. In the Advanced configuration section, turn on the Advanced configuration toggle.
    2. In the Dynamic currency conversion section, select the Activate dynamic currency conversion checkbox.
    3. Complete the required fields.
    Configure sticky gateway accounts

    Use this process to specify that all future payments from new payment instruments must be processed by the same gateway that processed their first transaction. For more information, see Sticky gateway accounts.

    1. In the Advanced configuration section, turn on the Advanced configuration toggle.
    2. In the Sticky gateway account section, select the Activate sticky gateway checkbox.
    Configure gateway account timeout

    Use this process to specify the amount of time that Rebilly will wait for a response from the gateway before timing out.

    1. In the Advanced configuration section, turn on the Show advanced configuration toggle.
    2. In the Gateway account timeout section, enter a value between 10 and 59 seconds.
    Configure approval window Time To Live (TTL)

    Use this process to specify the amount of time in which an offsite transaction must be approved before it is automatically abandoned.

    1. In the Advanced configuration section, turn on the Show advanced configuration toggle.
    2. In the Approval window Time To Live (TTL) section, enter a value, in seconds. Unapproved transactions are abandoned after this period.
    Configure reconciliation window

    Use this process to specify the amount of time in which an approved transaction must be reconciled before it is automatically abandoned.

    1. In the Advanced configuration section, turn on the Show advanced configuration toggle.
    2. In the Reconciliation window section, select the Activate reconciliation window checkbox.
    3. In the Time window field, enter the reconciliation period, in seconds.
    Configure 3D Secure (3DS)

    Use this process to activate 3DS transactions on a payment gateway account.

    3DS is a security layer for online credit and debit card transactions that is used by merchants to validate cardholders. The cardholder authenticates their card against the website of the issuing bank. The merchant chooses whether to use 3D secure. This enables the merchant to shift liability from themselves to the issuing bank. 3D Secure requires that cardholder interaction. 3D stands for the three domains which interact using the protocol: the merchant or acquirer domain, the issuer domain, and the interoperability domain.

    To use the Rebilly 3DS provider (3DSecure.io), you must obtain the following merchant information from your acquirer: acquirer Merchant Identification Number (MID) for both Visa and Mastercard, merchant name, acquirer Bank Identification Number (BIN) for Visa (automatic enrollment), acquirer BIN for Mastercard (manual enrollment), merchant country, and merchant URL.

    Mastercard enrollment must be initiated by the acquirer. The acquirer must enroll the specific acquirerBIN and acquirerMerchantID (for v2) into their system. Enrollment is completed by the acquirer using the Mastercard Connect ISSM tool.

    If required, Rebilly can provide all PCI DSS and PCI 3DS certification documentation. For assistance, contact Rebilly support.

    1. In the Advanced configuration section, turn on the Advanced configuration toggle.
    2. In the 3D Secure section, select the Activate 3D Secure checkbox.
    3. From the 3D server dropdown, select a server.
    4. Enter the merchant information you gathered from your acquirer.
    5. Select a version of 3DS.
    6. Select a transaction type from the dropdown.
    Configure additional filters

    Use this process to define additional criteria on when to use a specific payment gateway. For example, to only use this gateway account when the customer's billing address is in the US.

    1. In the Advanced configuration section, turn on the Advanced configuration toggle.
    2. In the Additional filters section, Click the select filter dropdown, then select an item to filter.
    3. Define your filter, and click Add filter.
      You can add multiple filters. To delete a filter, on the right of the filter, click Delete.
    Configure additional reporting

    Use this process to add additional reporting and benchmark information to a payment gateway.

    1. In the Advanced configuration section, turn on the Advanced configuration toggle.
    2. In the Additional information section, in the Acquirer dropdown, select an acquirer company.
    3. In the Merchant category code dropdown, select a code.
  13. Click Save gateway account.

  14. Perform test transactions. For applicable gateways, to test that your credentials are correct, at the top of the screen, click the Check credentials.

Instant payment notifications (IPNs)

IPN is a message service that automatically notifies merchants on transaction events. It is used to automate office administrative functions, including automatically fulfilling orders, and providing customers with order status.

Payment gateways use static or dynamic IPNs. Static IPNs must be configured within the user interface of the gateway, or in some cases, they may need to be set by your account manager. Dynamic IPNs are pre-configured and do not require any further action. If you are unsure whether your payment gateway uses static or dynamic IPNs, contact your gateway account manager.

All static IPNs have the following structure:

https://hook.rebilly.com/ipns/{gatewayName}/{merchantId}

Further reading