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.
Select an environment: In the top right corner of the page, press your initials and then select Sandbox or Live environment.
In the left navigation bar, press Settings .
In the Configuration section, press Gateway accounts.
Press Add gateway account.
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.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.
In the Payment methods section, select the payment methods you want active on this payment gateway.
In the Accepted currencies section, press in the Select currencies field and add one or more currencies.
Optionally, to define the setup instruction for new payment instruments:
In the Setup instruction section, press 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 bank to authenticate the customer. SCA requires the cardholder's interaction. For more information, see Configure 3D Secure (3DS) in the steps below.
Optionally, to configure how the gateway manages payout requests
- In the Ready to payout instructions section, turn on the Activate this gateway account for payouts toggle.
- 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.
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.
- In the Advanced configuration section, turn on the Advanced configuration toggle.
- 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.
- In the Advanced configuration section, turn on the Advanced configuration toggle.
- 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.
To use this feature, your payment gateway must support the currencies that you want to offer using DCC.
- In the Advanced configuration section, turn on the Advanced configuration toggle.
- In the Dynamic currency conversion section, select the Activate dynamic currency conversion checkbox.
- In the Conversion markup field, enter a value in basis points.
A basis point is 1/100th of a percent. For example, 200 basis points is the same as 2 percent. - In the Exclude currencies field, select currencies to exclude from dynamic currency conversion. Omit to apply to all currencies.
- In the Force conversion field, select the currency you want to convert all transactions to.
- To round the quoted amount to the nearest whole number, select the Force rounding checkbox.
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.
- In the Advanced configuration section, turn on the Advanced configuration toggle.
- 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.
- In the Advanced configuration section, turn on the Show advanced configuration toggle.
- 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.
- In the Advanced configuration section, turn on the Show advanced configuration toggle.
- 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.
- In the Advanced configuration section, turn on the Show advanced configuration toggle.
- In the Reconciliation window section, select the Activate reconciliation window checkbox.
- 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. For more information and how to configure 3DS, see 3D Secure.
In the Advanced configuration section, turn on the Advanced configuration toggle.
In the 3D Secure section, select the Activate 3D Secure checkbox.
From the 3D server dropdown, select ThreeDSecureIO3dsServer. This option uses the Rebilly 3DS provider (3DSecure.io). This server can be used in both live and sandbox environments.
For configuration requirements, see 3D Secure.
Enter the acquirer merchant IDs and acquirer merchant BINs for all payment cards you want to use with 3DS. At a minimum, you must enter details for Visa and Mastercard.
In the Merchant name field, enter your merchant name.
In the Merchant country dropdown, select a country.
In the Merchant URL field, enter a valid merchant URL.
In the Transaction type dropdown, select which transactions to use 3DS for.
Optionally, to decline transactions from customer that are not enrolled in 3DS: Select the Decline non-enrolled transactions checkbox.
Optionally, to use 3DS for merchant-initiated transactions:
- Select the Use 3DS for merchant-initiated transactions checkbox.
- To generate authentication data for authorization without directly involving the customer in the transaction: In the Merchant-initiated authentication (3RI) type dropdown, select an option.
To verify your 3DS configuration is working correctly, see Test a 3DS challenge flow.
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.
- In the Advanced configuration section, turn on the Advanced configuration toggle.
- In the Additional filters section, in the Filter dropdown, select a filter.
- In the Operation dropdown, select a condition.
- In the Value field, enter or select values.
- Press Add filter.
You can add multiple filters. To delete a filter, on the right of the filter, press Delete.
Configure additional reporting
Use this process to add additional reporting and benchmark information to a payment gateway.
- In the Advanced configuration section, turn on the Advanced configuration toggle.
- In the Additional information section, in the Acquirer dropdown, select an acquirer company.
- In the Merchant category code dropdown, select a code.
Press Save gateway account.
Complete test transactions. For applicable gateways, to test that your credentials are correct, at the top of the screen, press 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}