Configure devices

Process payments using terminal devices

Before a device can process payments, it needs to be registered to a merchant. This guide will explain how to:

  • Register and de-register a physical device in Production
  • Register and de-register virtual devices for testing in Sandbox

Register the device


Devices must be registered to a merchant in order to process payments, which is completed via the Rainforest API. You should integrate a flow in your platform for your merchants to register devices.

When the device is connected to the internet, an un-registered device will display:

  1. The device serial number (e.g. 123456789)
  2. Unregistered
  3. 6-digit registration code (e.g. Code: KBGBMJ)

The device is registered via the create device registration endpoint. You'll need to pass:

  • registration_code: the 6-digit registration code displayed on the device
  • merchant_id: the merchant to process payments on with the device
  • device_name: the friendly name of the device that will appear on the device
{
    "registration_code": "ABCDEF",
    "merchant_id": "sbx_mid_example",
    "device_name": "Example device"
}

Once the device is successfully registered, the friendly name will appear on the device.

The create device registration response contains a device_registration_id, which identifies the device when sending requests to present a payin on the device.

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

De-register the device


A device can be de-registered via the delete device registration endpoint. You may want to de-register a device to:

  • Associate the device to a different merchant
  • Give the device a new friendly name displayed on the device

Once the device is de-registered, it will immediately display a registration code on the device and is ready to be re-registered.


Sandbox simulation


Rainforest does not support physical devices in the Sandbox environment, . All device payment flows can be simulated in the Rainforest Sandbox environment utilizing a virtual device.

Register a virtual device

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

Supported devices in Production can have different capabilities, such as collecting a signature. Rainforest supports two virtual devices with different capabilities.

Register the device by passing one of the following registration codes:


// POST https://api.sandbox.rainforestpay.com/v1/device_registrations
// Authorization: Bearer {{API key}}
{
    "registration_code": "VIRTUAL_DEVICE",
    "merchant_id": "sbx_mid_example",
    "device_name": "Example device"
}