🚧

Upgrade to the latest version

These docs are for version 2023-12-01. We encourage you to upgrade to version 2024-10-16 to access new features. Please see the changelog for more information.

To accept in-person payments, you'll use the Rainforest API to interact with physical terminal devices where the customer can tap or swipe their card. By following this guide, you'll be able to take your first test payment in our sandbox environment, even without any hardware.

At a high level, taking a device payment involves three steps:

• Register a device so it can accept payments
• Configure a payment and present it on the device to be paid
• Listen to webhooks to find out when the payment succeeds or fails

Register a device

In Rainforest's sandbox environment, we support virtual devices instead of a physical device. This allows you to develop your integration without having to keep track of a physical device.

First, call the Rainforest API to register a device to your merchant:

// POST https://api.sandbox.rainforestpay.com/v1/device_registrations
// Authorization: Bearer {{API key}}
{
    "registration_code": "VIRTUAL_DEVICE",
    "merchant_id": "sbx_mid_example",
    "device_name": "Jenny's dev testing"
}

The response contains a device_registration_id, which identifies the device in later API calls.

{
    "status": "SUCCESS",
    "data": {
      "device_registration_id":"sbx_dvc_2SnJJG80tRUhMFmnJ7V0140dFth",
      // ... other attributes of the device
    }
}

Configure a payin

Now that you have a registered device, you can configure a payment that you'd like to accept on it. Call the Rainforest Pay API to create a payin config for the amount that you want to charge.

// POST https://api.sandbox.rainforestpay.com/v1/payin_configs
// Authorization: Bearer {{API key}}
{
    "merchant_id": "sbx_mid_example",
    "idempotency_key": "a unique id for this transaction, to avoid duplicates",
    "amount": "123",
    "currency_code": "USD",
}

The response contains a payin_config_id, which you should save for future use.

{
    "status": "SUCCESS",
    "data": {
        "payin_config_id":"sbx_cfg_2SnJJEMoszIxbP0kDYMmi5L6bai"
      	// ... other attributes of the PayinConfig
    }
}

Present the payin on the device

You can now call the Rainforest API to present the payin on the device, providing the previously-saved device ID in the URL, and the payin config ID in the body:

// POST https://api.sandbox.rainforestpay.com/v1/device_registrations/{{device_registration_id}}/payin
// Authorization: Bearer {{API key}}
{
    "payin_config_id": "{{payin_config_id}}"
}

📘

Note

A payment method created on a registered device may only be used for payins within the same merchant for which it was collected.

Simulate device interaction on sandbox

Once the payin has been presented on the device, the next step is asynchronous because you are waiting for something to happen on the device.

On a physical device in production, the customer would tap or swipe their card on the device, or possibly press the cancel button.

On the virtual device in sandbox, you can call our simulate device interaction API to test different scenarios. For example, to test the case where a Visa card is tapped on the device and then creates a successful payment, you would call:

// POST https://api.sandbox.rainforestpay.com/v1/device_registrations/{{device_registration_id}}/simulatete
// Authorization: Bearer {{API key}}
{
    "event": "PRESENTED",
    "card": "VISA_SUCCESS"
}

Listen to webhooks

Because the interaction on the device is asynchronous, you will need to register webhook listeners to get the final status of the payin. You will receive a payin.processing, payin.failed, or payin.canceled event:

Your system should handle these events and translate them into your own terms.

• On a successful payin, you should show success to whoever is operating the physical device. You might also then ship an order, provision a service, or mark something paid in an accounting system.
• On a failed payin, make sure you allow the option to re-present the payment on the device in your point-of-sale or other system. Or you may need to contact the customer and have them pay in some other way.

Simulate release and deposit

In the real world, a payin will stay in the processing status until it is released to your merchant and sent to them in a Deposit. This can take a variable amount of time, depending on your platform's risk policies, weekends and holidays, and other factors.

In sandbox, you can easily test this out without having to wait. Call the Simulate merchant deposit creation endpoint for a merchant to test out what their next deposit would be like. This call will take all of the merchant's payins in the processing status, release them as if enough time had passed, and create the Deposits that would be sent to the merchant.

Next steps

Now that you can accept device payments in sandbox, you might next:

• Show the Payment report and Deposit report in your dashboard so that your merchants can manage their payments and understand their deposits
• Accept online payments with the Payment component
• Move to production and prepare to work with physical devices.
  • When registering physical devices, instead of using "registration_code": "VIRTUAL_DEVICE", you will need to specify an actual registration code, which appears as a randomly-generated 6 letter code shown on the device's display (i.e LYMVZC). You will first need to get your merchant into your application and collect the device code from them, then pass that to the Rainforest device registration call.
  • When one of your merchants stops using a device, returns a device, or you want to use it with another merchant, you can use the delete device registration API call to de-register the device from its former merchant. You can then register it again, to a different merchant.

Limitations

A payment method created on a registered device will always have a fingerprint value of null. Rainforest is unable to access the full credit card number for payment methods created via a registered device, so a fingerprint value cannot be generated.