✔️
Feature requirements
🔐 Rainforest must enable the platform to access this feature
⬆️ Only available on the API versions 2024-10-16 and 2023-12-01

You can implement an IVR payments integration with three steps:

Enable the IVR payments feature on your platform
Integrate with Twilio in sandbox
Integrate with Twilio in production

Enable IVR payments

If you are interested in the IVR integration, please reach out to your Platform Success Manager or support to enable this feature.

Integrate with Twilio in sandbox

Follow the Twilio Generic Pay Connector guide on how to install and configure a Generic Pay Connector. You'll need to configure a Twilio integration for both Sandbox and Production.

Create an API key

In the Rainforest Sandbox Platform Portal, create an API key that only has specific permissions to complete the 2nd step of processing a payin or storing a payment method. This API key should not be able to create payin configs or payment method configs, ensuring if the API key was compromised it would not have the abilities to process payments with Rainforest.

Determine if you're integration will have the ability to:

In the Portal, click on the "Advanced" dropdown to allow you to update the statements to define the API key permissions.

Process payins

If your integration will only be used to process payins, then create an API key that only has the ability to create payins by setting the permissions to only include payin:create:

[
  {
    "permissions": [
      "payin:create"
    ],
    "constraints": {
      "platform": {
        "platform_id": "{{platform_id}}"
      }
    }
  }
]

Each request to process a payin requires a payin config to be configured first. This API key should not be able to create payin configs, ensuring the API key only has permissions to do the 2nd step of processing a payin.

Store payment methods

If your integration will only be used to store payment methods, then create an API key that only has the ability to create payment methods by setting the permissions to only include payment_method:create:

[
  {
    "permissions": [
      "payment_method:create"
    ],
    "constraints": {
      "platform": {
        "platform_id": "{{platform_id}}"
      }
    }
  }
]

Each request to store a payment method requires a payment method config be configured first. This API key should not be able to create payment method configs, ensuring the API key only has permissions to do the 2nd step of storing a payment method.

Process payins and store payment methods

If your integration will be able to process payins and store payment methods, then create an API key that has the abiliy to create payins and payment methods by setting the permissions to include payin:create and payment_method:create:

[
  {
    "permissions": [
      "payin:create",
      "payment_method:create"
    ],
    "constraints": {
      "platform": {
        "platform_id": "{{platform_id}}"
      }
    }
  }
]

Each request to process a payin requires a payin config to be configured first and each request to store a payment method requires a payment method config to be configured first. This API key should not be able to create payin configs or payment method configs, ensuring the API key only has permissions to do the 2nd step of processing a payin or storing a payment method.

Merchant constraint

If your Twilio integration will be configured per merchant, then the API key should be constrained to the specific merchant:

[
  {
    "permissions": [
      "payin:create"
    ],
    "constraints": {
      "platform": {
        "platform_id": "{{platform_id}}"
      },
      "merchant": {
        "merchant_id": "{{merchant_id}}"
      },
    }
  }
]

This will require a separate Generic Pay Connection configuration per merchant, which is explained below.

Configure the Generic Pay Connector

On the Configure the Generic Pay Connector section of the Twilio guide, for step 2 to add the credentials for the payment processor, configure the following fields:

Field	Value
Unique Name	Give the Generic Pay Connector a unique name for your Sandbox integration with Rainforest
Username	Set this value to `api_key`
Password	Set this to the API key created specifically for the Twilio integration, it should only have permission to create a payin and/or create a payment method.
Endpoint URL	Set this value to `https://api.sandbox.rainforestpay.com/vendor/twilio/pay_generic`

No-code integration

If configuring Twilio through a no-code Twilio Studio integration, then follow this section. If configuring through code, continue to the next section.

In your IVR flow, once you're ready to process a payment or store a payment method, add a "Capture Payment" widget with the following configuration:

Field	Value	Description
Valid Card Types	Visa, Master Card, American Express, Discover, JCB, Diners Club	Rainforest can process payments from this list of card types.
Request Security Code	Yes	Requesting the security code increases the approval rates for Card Not Present payments.
Request Postal Code	Yes	Requesting the postal code increases the approval rates with AVS check and reduces interchange downgrades. The postal code can also be collected separately and passed into the Payin Config.
Pay Connector	The Unique Name of the Generic Pay Connector	This was configured in the above step for "Unique Name" when configuring the Generic Pay Connector.
Payment Token Type	Reusable	Set this value to "Reusable"
Charge Card with Amount	Amount or empty	To process a payin, set this value to match the amount specified in the Payin Config. To store a payment method, leave this field empty.
Currency	US Dollar (USD)	Rainforest can only process payments in USD.
Payment Method	credit-card	Rainforest only supports credit card payments through the Twilio integration.
Parameters	payin_config_id or payment_method_config_id	To process a payin, add a custom parameter `payin_config_id` and pass the identifier in the value. To store a payment method, add a custom parameter `payment_method_config_id` and pass the identifier in the value.

Code integration

If configuring Twilio through TwiML for Programmable Voice, then follow this section.

In your IVR flow, once you're ready to process a payment or store a payment method, integrate the TwiML Pay verb with the following configuration:

Field	Value	Description
`validCardTypes`	`visa`, `mastercard`, `amex`, `discover`, `jcb`, `diners-club`	Rainforest can process payments from this list of card types.
`securityCode`	`true`	Requesting the security code increases the approval rates for Card Not Present payments.
`postalCode`	`true`	Requesting the postal code increases the approval rates with AVS check and reduces interchange downgrades. The postal code can also be collected separately and passed into the Payin Config.
`paymentConnector`	The Unique Name of the Generic Pay Connector	This was configured in the above step for "Unique Name" when configuring the Generic Pay Connector.
`tokenType`	`reusable`	Set this value to `reusable`
`chargeAmount`	Amount in decimal or `0`	To process a payin, set this value to match the amount specified in the Payin Config. To store a payment method, set this field to `0`.
`currency`	`usd`	Rainforest can only process payments in USD.
`paymentMethod`	`credit-card`	Rainforest only supports credit card payments through the Twilio integration.
`parameter`	`payin_config_id` or `payment_method_config_id`	To process a payin, add a custom parameter `payin_config_id` and pass the identifier in the value. To store a payment method, add a custom parameter `payment_method_config_id` and pass the identifier in the value.

Payin config or payment method config

In your integration, you'll need to create a payin config or create a payment method config in order to process a payin or store a payment method, respectively.

Twilio parameter

The config ID must be passed into the Twilio request by adding a custom parameter in the Capture Payment widget (for the no-code integration) or passing a custom parameter into the Pay verb (for the code integration).

Payin config

If processing a payin, set the key to payin_config_id and pass the payin config ID into the value.

Payment method config

If storing a payment method, set the key to payment_method_id and pass the payment method config ID into the value.

Amount

Payin config

If processing a payin, the amount in the payin config must match the Charge Card with Amount in the Capture Payment widget (for the no-code integration) or the chargeAmount field in the Pay verb (for the code integration). If the amounts do not match, then an error will be returned to the request from Twilio.

Payment method config

If storing a payment method, the Charge Card with Amount should be empty in the Capture Payment widget (for the no-code integration) or the chargeAmount field should be set to 0 in the Pay verb (for the code integration).

Metadata

Metadata can be set in the config. It's recommended to pass a metadata key/value that indicates the payin was processed via the Twilio integration.

Integrate with Twilio in production

Once your integration on Sandbox is complete, follow this section on how to integrate with Twilio in Production.

Create an API key

In the Rainforest Platform Portal, create an API key with the same constraints explained in the sandbox section, ensuring the API key only has specific permissions to complete the 2nd step of processing a payin or storing a payment method.

Configure the Generic Pay Connector

Configure a separate Generic Pay Connector for your Production integration. For step 2 to add credentials for the payment processor, configure the following fields:

Field	Value
Unique Name	Give the Generic Pay Connector a unique name for your Production integration with Rainforest
Username	Set this value to `api_key`
Password	Set this to the API key created specifically for the Twilio integration, it should only have permission to create a payin and/or create a payment method.
Endpoint URL	Set this value to `https://api.rainforestpay.com/vendor/twilio/pay_generic`

Request Twilio live mode

Follow the steps in the Twilio guide to request LIVE mode with your Production Generic Pay Connector configured above with Twilio support.

Attestation of Compliance (AOC)

You'll need to provide Twilio with Rainforest's Attestation of Compliance (AOC) documentation. Please reach out to your Platform Success Manager or support to obtain Rainforest's AOC.

URL of the payment gateway

You'll need to provide Twilio with the Rainforest URL for the Twilio integration:

https://api.rainforestpay.com/vendor/twilio/pay_generic

This should match the URL configured in the Generic Pay Connector Endpoint URL field.

Integrate the Generic Pay Connector

Duplicate your Sandbox integration, either through the no-code integration or the code integration, for your Production integration.

No-code integration

Set the Pay Connector in the Capture Payment widget to the Unique Name set in the Production Generic Pay Connector configured above.

Code integration

Set the paymentConnector field in the Pay verb to the Unique Name set in the Production Generic Pay Connector configured above.

Once Twilio approves your integration and moves to LIVE mode, your integration with Rainforest's IVR system in Production is complete.