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

Devices must be registered to a merchant in order to process payments. When the device is connected to the internet, the device will display a 6 letter code.

Register the device by passing the registration code displayed on the device in the registration_code field.

{
    "registration_code": "ABCDEF",
    "merchant_id": "sbx_mid_example",
    "device_name": "Example device"
}

The 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
    }
}

Configure a payin

Once a device is registered, you'll need to configure the payment that you'd like to present on the device. Create a payin config for the amount of the payment and other information, such as billing contact and metadata.

// 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 that you'll need in the next step.

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

Present the payin on the device

With a registered device and payin config, present a payin on a registered device by providing the device registration ID and payin config ID:

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

This will return a payin_id for the payin currently presented on the device. The status of the payin will be Presenting.

{
    "status": "SUCCESS",
    "data": {
        "payin_id":"sbx_pyi_2pic60IODoGBzCz8x3wN8USjvrO",
        "status": "PRESENTING"
      	// ... other attributes of the Payin
    }
}

📘

Note

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

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.

Query for the status of the payin

An alternative to listening to webhooks would be to query the Rainforest API get payin endpoint to check when the status of the payin updates from Presenting to the final status. The final status of the payin will be one of the following:

Sandbox simulation

All device interactions can be simulated on 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.

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

• VIRTUAL_DEVICE
• VIRTUAL_DEVICE_SIGNATURE - supports signature collection on a device

// 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"
}

Simulate device interaction

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"
}

Simulate deposit and payments to succeeded

In Production, a payin will stay in the processing status until it is released to your merchant and sent to them as part of 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. Simulating a deposit will do the following:

1. Take all of the merchant's payins, refunds, and other payments in the Processing status and move them to the Succeeded status.
2. Process a Deposit that would be sent to the merchant.

Once the payments are in the Succeeded status, actions such as refunding can be taken on the payins.

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.