Component sessions

Make money move with robust payment flows

A session is a short-lived credential with a maximum lifetime of 24 hours (86,400 seconds). Sessions can be generated at any point before a component is rendered, but in general, it's preferable to create a session at the same time as your application creates it's internal session.

Sessions are designed to be transmitted to the front-end for component permissions. They should have carefully scoped permissions that only allow access to the resources and data that should be accessible to the requesting user.

Defining a statement

A statement consists of a set of permissions and constraints that defines what resources and actions this session can access.

What is a resource?

A resource is an object in the Rainforest API (e.g. payins, refunds, chargebacks, merchants, etc.).

Valid resources

ResourceDescription
api_keyAPI key
billing_profileBilling profile
chargebackChargeback
depositDeposit
deposit_methodDeposit method
deposit_method_configDeposit method config
device_registrationDevice registration
http_requestHTTP request
mccMerchant commerce code
merchantMerchant
merchant_applicationMerchant application
payinPayin
payin_configPayin config
payment_methodPayment method
payment_method_configPayment method config
plaid_linkPlaid link
platformPlatform
refundRefund
routing_numberRouting number
sessionSession
threeds_attempt3DS attempt
userUser

What is an action?

An action is a specific operation on a resource in the Rainforest API.

Valid actions

ActionDescription
createCreate a new resource (e.g, creating a payin_config or payin)
updateUpdate a resource (e.g. updating a merchant_application)
readRead a resource (e.g. reading a payin_config)
deleteDelete a resource (e.g. deleting a session)

What is a permission?

A permission is the combination of a resource and an action in the format resource:action, which determines a specific capability on the Rainforest API (e.g. payin:create).

Most API keys and sessions will include multiple permissions in order to facilitate more complex API interactions. While these can be enumerated explicitly, it's generally preferable to use a group.

What is a group?

A group is a collection of permissions. These groups are defined by Rainforest, and will define a collection of permissions needed to integrate with Rainforest Components.

Groups enable you to:

  • Simplify and better understand your permissions.
  • Allows Rainforest to introduce new features in the Rainforest Components and if they require new resources or actions, then your users will automatically be able to take advantage of them without you needing to update your integration code.

Valid groups

GroupCapabilities
group#allGives full access to all actions on Rainforest resources.
group#ach_return_details_componentSee ACH return details.
group#chargeback_details_componentSee chargeback details.
group#deposit_details_componentSee details of a given deposit and open payin, refund, ACH return and chargeback details.
group#deposit_details_component.create_refundCreate a refund on the payin details from within the deposit details component.
group#deposit_report_componentSee all deposits and deposit details, which includes payins, refunds, ACH returns, and chargebacks.
group#deposit_report_component.create_refundCreate a refund on the payin details from within the deposit report component.
group#merchant_onboarding_componentUpdate and submit a merchant application in the merchant onboarding component.
group#payin_details_componentSee payin details in the payin details component.
group#payin_details_component.create_refundCreate a refund in the payin details component.
group#payin_receipt_componentSee payin details in the payin receipt component.
group#payment_componentCreate a payin or payment method from the payment component.
group#payment_report_componentSee ACH return, chargeback, payin, and refund details within the payment report component.
group#payment_report_component.create_refundCreate a refund on the payin details page within the payment report component.
group#refund_details_componentSee payin and refund details within the refund details component.

What is a constraint?

A constraint restricts what actions are allowed based on the specific context of a resource. For example, constraints can be used to limit credentials to a specific merchant and might look like the following:

"merchant": {
    "merchant_id": "mid_123"
}

This will only allow the session to perform actions on resources whose merchant has the merchant_id of mid_123. If a resource does not have a parent merchant (e.g. a platform, or a merchant itself), this will be skipped.

Any field returned by the API for a given resource Get by ID endpoint can be used in a constraint, including metadata.

What is a statement?

A statement is a set of permissions and constraints that must be met in order to complete the API interaction. A session is composed of multiple statements. While most sessions will only need a single statement, if multiple statements are specified, only one statement needs to be satisfied for the action to be allowed. Statements are OR'd together.

Here is an example of creating a session that is authorized to perform all actions on all resources, unless that resource has a parent merchant (e.g. payins, payin_configs, etc). If a parent merchant exists, it must match the provided constraint, meaning it must have a merchant_id of mid_123. If a parent merchant does not exist, the constraint will be ignored.

curl --location 'https://api.rainforestpay.com/v1/sessions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{api_key}}' \
--data '{
    "ttl": 86400,
    "statements": [
        {
            "permissions": ["group#all"],
            "constraints": {
                "merchant": {
                    "merchant_id": "mid_123"
                }
            }
        }
    ]
}'

Groups can be combined to grant additional permissions for a given component. Here is an example of creating a session that is authorized to do the basic functionality on the Payin Details component, such as read the payin and associated refunds, as well as create refunds.

curl --location 'https://api.rainforestpay.com/v1/sessions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{api_key}}' \
--data '{
    "ttl": 86400,
    "statements": [
        {
            "permissions": ["group#payin_details_component", "group#payin_details_component.create_refund"],
            "constraints": {
                "merchant": {
                    "merchant_id": "mid_123"
                }
            }
        }
    ]
}'

Permissions can also be enumerated explicitly, with more complex constraints. The following is an example of a session that is authorized to create, read, delete and update payins and nothing else. This constraint requires that the payin have an internal_id metadata key with 987654321 as the value.

curl --location 'https://api.rainforestpay.com/v1/sessions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{api_key}}' \
--data '{
    "ttl": 86400,
    "statements": [
        {
            "permissions": ["payin:create", "payin:read", "payin:delete", "payin:update"],
            "constraints": {
                "payin": {
                    "metadata": {
                        "internal_id": "987654321"
                    }
                }
            }
        }
    ]
}'

TTL

Sessions are temporary and must have a time to live in seconds. The maximum allowed TTL is 24 hours (86400 seconds).

Session key

Once you create a session, the session_key can be passed into a Rainforest component in the session-key prop.

Request

curl --request POST \
--url 'https://api.rainforestpay.com/v1/sessions' \
--header 'Authorization: Bearer {{api_key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "ttl": 3600,
  "statements": [
  	{
    	"permissions": ["group#all"],
      "constraints": {
      	"merchant": {
        	"merchant_id": "mid_123"
        }
      }
    }
  ]
}'

Response

{
    "status": "SUCCESS",
    "data": {
        "session_id": "ses_2IrcnEso2z8vFbsdNb7COwoityc",
        "session_key": "session_35c2bb7f5dcc0116d16a47305cabe92206a7a6c2dac9282689aa34fccda1f4d7",
        "statements": [
          {
            "permissions": ["group#all"],
            "constraints": {
              "merchant": {
                "merchant_id": "mid_123"
              }
            }
          }
        ],
        "expires_at": "2022-12-13T10:55:07.22893-05:00"
    },
    "errors": null
}

Component

<rainforest-example-component 
	session-key="session_35c2bb7f5dcc0116d16a47305cabe92206a7a6c2dac9282689aa34fccda1f4d7"
></rainforest-example-component>