Once a device is registered to a merchant, it's ready to store payment methods.

Storing a payment method involves three steps:

• Create a payment mehod config via the Rainforest API to send information about the payin (amount, user billing contact, metadata, etc.)
• Present the payin on the device
• Listen to webhooks or poll the API to know the result of the payin

Configure the payment method

First, create the payment method config to configure the payment method with information, such as billing contact and metadata, before collecting the sensitive payin details (i.e the card number) via the device.

With the payment method config, you can also specify if you'd like to collect a signature from the User on the device, if the device supports signature collection.

The payment_method_config_id from the response will be used to present the payment method on the device in the next step.

{
    "status": "SUCCESS",
    "data": {
        "payment_method_config_id":"pmc_2SnJJEMoszIxbP0kDYMmi5L6bai"
      	// ... other attributes of the payment method config
    }
}

Present the payment method on the device

Present the payment method on a registered device by providing the device registration ID and payment method config ID:

// POST https://api.rainforestpay.com/v1/device_registrations/{{device_registration_id}}/paymenth_method
{
    "payment_method_config_id": "{{payment_method_config_id}}"
}

Success

If the payment method is successfully presented on the device, the response will include a payment_method_id for the payment method currently presented on the device and the status of the payment method will be Presenting.

{
    "status": "SUCCESS",
    "data": {
        "payment_method_id":"mtd_2pic60IODoGBzCz8x3wN8USjvrO",
        "status": "PRESENTING"
      	// ... other attributes of the payment method
    }
}

Error

There are scenarios where Rainforest is not able to present the payment method on the device. If this occurs, the request will return with a status code 400 bad request. The following are some reasons the request may error:

🚧

Device payment methods are restricted to a single merchant

Devices are registered to a single merchant and payment methods stored via a device can only process payins on the merchant associated with the device.

Cancel the payment method on the device

The device interaction can be canceled in two ways:

• The user presses the cancel button the device
• The merchant requests the cancel via the Rainforest API cancel endpoint

Canceling a payment method presented on a device via the Rainforest API is a best effort attempt. Rainforest cannot guarantee the presented payment method can be canceled because the user may have already tapped or swiped their card on the device.

You should listen to webhooks or query the API to know the final status of the payment method. If we were successfully able to cancel the payment method, then the payment method status will move to Canceled.

If we were unable to cancel the payment method and the payment method status moves to Active.

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 payment method. You will receive one of the following events once the payment flow on the device has completed:

Query for the payment method status

An alternative to listening to webhooks would be to query the Rainforest API get payment method endpoint to check when the status of the payment method updates from Presenting to the final statuses.

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.

Device interactions

Once the payment method has been presented on the device, the next step is asynchronous because you are waiting for the interaction to complete on the device.

On a physical device in Production, the user would tap or swipe their card on the device to complete the payment flow, or press the cancel button to cancel the payment flow.

On the virtual device in Sandbox, you can simulate various scenarios with the simulate device interaction endpoint. For example, to test the case where a Visa card is tapped on the device and then successfully stores a payment method, you would pass the event PRESENTED and the card VISA_SUCCESS:

{
    "event": "PRESENTED",
    "card": "VISA_SUCCESS"
}

The payment method can then be used to process a payin from the stored payment method. The payment flow will simulate a Processing or Failed payin depending on the stored payment method and if it is in the Approved or Declined category defined in the test cards.