---
updatedAt: 2025-11-29T15:49:39.000Z
agentTools:
  projectIndex: https://docs.rainforestpay.com/llms.txt
---

# Payment report component

Embed the Rainforest payment report component

The payment report component displays payins and refunds (collectively, payments). Each payment can be opened to display additional details and actions associated to the payment, such as refunding a payin.

The payment report component can be utilized for a variety of reports based on your use case. The report can be filtered by various fields, such as status, date, payment type, or metadata (i.e. customer name, product ID, sales channel, etc.). Clicking on any payment generates a payment detail view.

<Image align="center" border={false} width="90% " src="https://files.readme.io/4ac42617322db7ae14e9d30b6ffb92fbcf5e28bf047d0b0200d0b2e06649fea4-rainforest_payment_report.png" />

# How to embed a payment report

***

## Session authentication

[Create a session](https://docs.rainforestpay.com/reference/create_session) to grant the payment report component permissions to view and action payments. The session should include at least the following permissions to view payments:

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

### Session constraints

If the component permissions are [constrained](https://docs.rainforestpay.com/docs/component-sessions#what-is-a-constraint)  to a specific resource, [data filters](https://docs.rainforestpay.com/docs/payment-report-component#data-filters) will need to be applied to give the payment report component the same level of permissions.

Commonly, the payment report is pre-loaded to show payments for a single merchant. The session should be constrained to a specific merchant to ensure this session only has permissions to view the payments associated to the merchant:

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

### Refund permissions

If the user should be able to refund a payin, then the session should include the `payment_report_component.create_refund` permission group:

```diff
{
    "ttl": 86400,
    "statements": [
        {
            "permissions": [
                "group#payment_report_component",
+               "group#payment_report_component.create_refund"
            ],
            "constraints": {
                "merchant: {
                    "merchant_id": "REPLACE_ME"
                }
            }
        }
    ]
}
```

### Chargeback permissions

If the user should be able to respond to a chargeback, then the session should include the `payment_report_component.update_chargeback` permission group:

```diff
{
    "ttl": 86400,
    "statements": [
        {
            "permissions": [
                "group#payment_report_component",
+               "group#payment_report_component.update_chargeback"
            ],
            "constraints": {
                "merchant: {
                    "merchant_id": "REPLACE_ME"
                }
            }
        }
    ]
}
```

## JavaScript bundle

Include the merchant [JavaScript bundle](https://docs.rainforestpay.com/docs/javascript-bundle) in your frontend to access the payment report component.

```html
<script type="module" src="https://static.rainforestpay.com/sandbox.merchant.js"></script>
```

## Payment report component

Add the Rainforest payment report component with custom configuration designed in the [component studio](https://static.rainforestpay.com/demo-sandbox/studio.html?type=payment_report).

```html
<rainforest-payment-report
    session-key="REPLACE_ME"
></rainforest-payment-report>
```

## Customize the component

Head over to the [Component Studio](https://static.rainforestpay.com/demo-sandbox/studio.html?type=payment_report) for more attributes you can provide to customize the component's appearance and behavior.

<Embed url="https://static.rainforestpay.com/demo-sandbox/studio.html?type=payment_report" href="https://static.rainforestpay.com/demo-sandbox/studio.html?type=payment_report" typeOfEmbed="iframe" height="600px" width="90%" iframe="true" />

### UI customization

It's possible to provide customized UI to the Payment Report through our exposed [slots](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot).

#### Available Slots

| Name                        | Description                                                                              |
| :-------------------------- | :--------------------------------------------------------------------------------------- |
| `details-loading-indicator` | Overrides the default "Loading..." UI shown while loading the relevant Details Component |

Example:

```html html
<rainforest-payment-report>
     <div slot="details-loading-indicator">
         (your custom UI markup)
     </div>
</rainforest-payment-report>
```

## Prop configuration

Rainforest supports prop attributes to configure the Payment Component with various functionality and styling. See the [Component Studio](https://static.rainforestpay.com/demo-sandbox/studio.html?type=payment_report) for a full list of attributes and valid values.

### Respond to chargebacks

If the user should be able to respond to a chargeback, then the `show-chargeback-respond-button` prop must be included when embedding the Payment Report Component:

```html
<rainforest-payment-report
    show-chargeback-respond-button
></rainforest-payment-report>
```

## Column configuration

The payment report will load with a set of default columns. Simply omit the `columns` prop to use the following default columns.

```json
[
    {"name": "Created", "type": "builtin", "value": "created"},
    {"name": "Type", "type": "builtin", "value": "type"},
    {"name": "Status",  "type": "builtin",  "value": "status"},
    {"name": "Amount",  "type": "builtin", "value": "amount"},
    {"name": "Customer", "type": "builtin",  "value": "name"},
    {"name": "Method", "type": "builtin",  "value": "method"},
    {"name": "Merchant Name", "type": "builtin", "value": "merchant_name"}
]
```

### Custom configuration

Columns can be **customized** to fit the needs of your platform. To override the default columns for the payment report, pass in the column specifications via a JSON payload in the `columns` prop.

```html
<rainforest-payment-report
    columns='[{"name":"My Custom Column Name","type":"builtin","value":"id"}]'
></rainforest-payment-report>
```

A column specification needs a `name`, `type`, and `value`.

* `name` - The display header name for the column.
* `type` - Set to `builtin` or `metadata`
* `value` - The key corresponding to a value returned from the [list payments](https://docs.rainforestpay.com/reference/list_payments) endpoint.

### Valid column values

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        Type
      </th>

      <th>
        Value
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        builtin
      </td>

      <td>
        id
      </td>

      <td>
        The unique identifier for this payment activity. Corresponds to the id field, representing a `payin_id` or `refund_id`.
      </td>
    </tr>

    <tr>
      <td>
        builtin
      </td>

      <td>
        merchant_id
      </td>

      <td>
        The unique merchant identifier. Corresponds to the `merchant_id` field.
      </td>
    </tr>

    <tr>
      <td>
        builtin
      </td>

      <td>
        merchant_name
      </td>

      <td>
        The name of the merchant. Corresponds to the `merchant.name` field.
      </td>
    </tr>

    <tr>
      <td>
        builtin
      </td>

      <td>
        created
      </td>

      <td>
        The datetime the payment activity was created at. Corresponds to the `created_at` field.
      </td>
    </tr>

    <tr>
      <td>
        builtin
      </td>

      <td>
        amount
      </td>

      <td>
        The amount of this activity. Corresponds to the `amount` field.
      </td>
    </tr>

    <tr>
      <td>
        builtin
      </td>

      <td>
        merchant_fees
      </td>

      <td>
        The amount of the payment activity billed to the merchant. Corresponds to the `merchant_fees` field.
      </td>
    </tr>

    <tr>
      <td>
        builtin
      </td>

      <td>
        name
      </td>

      <td>
        The billing contact name for this activity. Corresponds to the `billing_contact.name` field.
      </td>
    </tr>

    <tr>
      <td>
        builtin
      </td>

      <td>
        billing_contact_email
      </td>

      <td>
        The billing contact email for this activity. Corresponds to the `billing_contact.email` field.
      </td>
    </tr>

    <tr>
      <td>
        builtin
      </td>

      <td>
        type
      </td>

      <td>
        The type of payment activity. Set to PAYIN or REFUND. Corresponds to the `payment_type` field.
      </td>
    </tr>

    <tr>
      <td>
        builtin
      </td>

      <td>
        status
      </td>

      <td>
        The status of the payment activity. Corresponds to the `status` field.
      </td>
    </tr>

    <tr>
      <td>
        builtin
      </td>

      <td>
        method
      </td>

      <td>
        The payment method for this activity. Corresponds to the `method_type` field and the last 4 digits of the card or bank account.
      </td>
    </tr>

    <tr>
      <td>
        builtin
      </td>

      <td>
        expected_deposit_date
      </td>

      <td>
        The expected deposit date for this activity. Corresponds to the `expected_deposit_date` field.

        See the [payments expected deposit date](https://docs.rainforestpay.com/docs/deposit-timing-for-payments#payment-expected-deposit-date) guide for details and limitations on this field.
      </td>
    </tr>

    <tr>
      <td>
        metadata
      </td>

      <td>
        JSONPath to metadata key
      </td>

      <td>
        The metadata for this activity. Corresponds to the `metadata` field.
      </td>
    </tr>
  </tbody>
</Table>

### Metadata column

A column can be configured to display a custom metadata value passed into the config requests for varying payment activities. The `value` for type `metadata` should be valid JSONPath to a corresponding metadata key.

For example, a payin created with the following metadata

```json
{
    "account": {
        "id": "123",
        "name": "Jane Doe",
        "email": "jane.doe@example.com
    }
}
```

could have the following column specification to display the metadata account id

```json
{
    "name": "Account ID",
    "type": "metadata",
    "value": "$.account.id"
}
```

#### Filter type

When configuring a metadata column, you can set the filter type to allow the user to filter the metadata column in the embedded report for text, numbers, or date.

Available values for the `filter_type` field:

* `text` - text input, matching on the prefix
* `number` - number input, matching on the prefix
* `date` - date input, within the range provided

```json
{
    "name": "Account ID",
    "type": "metadata",
    "value": "$.account.id",
		"filter_type": "text"
}
```

### Templating columns

If you need to format the metadata for presentation to your users, you can also specify a template pattern. In order to show the Account ID as above, but formatted as "Account #123". You could specify a template string, and the pattern `{{value}}` will be replaced with the value of the field:

```json JSON
{
    "name": "Account ID",
    "type": "metadata",
    "value": "$.account.id",
    "template": "Account #{{value}}"
}
```

#### Hyperlinks

The template can also be valid HTML in order to make a metadata column a hyperlink. For example, in order to make an email a mailto hyperlink:

```json
{
    "name": "Email",
    "type": "metadata",
    "value": "$.account.email",
    "template": "<a style=\"color:blue;text-decoration:underline;\" href=\"mailto:{{value}}\">{{value}}</a>"
}
```

## Data filters

The payment report can be pre-loaded with a defined set of filters, including sort by and sort order. Data filters are defined by a JSON payload of key-value pairs passed into the `data-filters` prop.

A valid `key` includes any of the query params from the [list payments](https://docs.rainforestpay.com/reference/list_payments) endpoint. To pass multiple values for a given key, the value can be defined as an array of values.

```json
{
    "merchant_id": "mid_123",
    "status": ["PROCESSING", "FAILED"],
    "sort_by": "created_at",
    "sort_order": "desc"
}
```

Data filters will always be applied to the report and any additional filtering via the component will be in addition to the filters passed in.

### Component session contraints

If the component session includes [constraints](https://docs.rainforestpay.com/docs/component-sessions#what-is-a-constraint)  to a specific resource, such as a merchant, then the **data filters must be at least as restrictive**. Component sessions will *not* filter reporting and you must define the necessary constraints via data filters. This will constrain the reporting component to only load the data that the session permissions has access to.

For example, if the payment report should only show payments for a specific merchant, then the component session should be constrained to a merchant:

```json
{
    "permissions": ["group#payment_report_component"],
    "constraints": {
        "merchant": {
            "merchant_id": "REPLACE_ME"
        }
    }
}
```

And the payment report should pre-load the list of payments filtered to the specific merchant:

```html
<rainforest-payment-report
    session-key="REPLACE_ME"
    data-filters={"merchant_id": "REPLACE_ME"}
></rainforest-payment-report>
```

If the report is attempting to load payments that the session permissions do not have access to, the request will error with a status code of `401 Unauthorized` and the response will include helpful information as to why this request is not valid:

```json
{
    "status": "ERROR",
    "data": null,
    "errors": [
        {
            "field": "Authorization",
            "code": "AuthUnauthorized",
            "message": "Permission denied: Request parameter not specified for constraint merchant"
        }
    ]
}
```

### Metadata

Metadata can be utilized to constrain the payment report to payments that share a common metadata value.

For example, if the payment report should only show payments for a specific account defined by the platform, then the component session can be constrained to a metadata `account_id` defined on the payin:

```json
{
    "permissions": ["group#payment_report_component"],
    "constraints": {
        "payin": {
            "metadata": {
              "account_id": "123"
            }
        }
    }
}
```

And the payment report should pre-load the list of payments filtered to the `account_id`:

```html
<rainforest-payment-report
    session-key="REPLACE_ME"
    data-filters={"metadata[$.account_id]": "123"}
></rainforest-payment-report>
```

Payin metadata is persisted to the related payments, such as refunds, chargebacks, and ACH returns. Constraining a session to a payin metadata field will grant permissions to view all payments (payins, refunds, chargebacks, and ACH returns) with the specified metadata.

# Export payments

***

Payments may be exported to a comma-separated values (CSV) file. By setting the `show-export-button` attribute on the payment report component, an export button will appear on the top right of the component.

```html
<rainforest-payment-report
    session-key="REPLACE_ME"
    show-export-button
></rainforest-payment-report>
```

<Image align="center" alt="Export button displayed at the top right" border={false} caption="Export button displayed at the top right" src="https://files.readme.io/9f49366038f59ec6faa2f4dfcf362dd999af6385d4ae7b088f92236b5b2fa656-rainforest_payment_report.png" />

## Date ranges

Default date ranges for the previous or current month may be selected. If a custom date range is chosen, a maximum of 31 days may be exported.

<Image align="center" alt="Payment report export modal" border={false} caption="Payment report export modal" src="https://files.readme.io/d931a7e88cc6a648724228d75300a7561e274758bd2c7a6cb747332bd1a107df-rainforest_payment_report_export.png" />

## Payment filters

Any filters applied when the user is interacting with the payment report will be automatically applied to the exported payment report data. These filters can be cleared by utilizing the "Clear filters" link before clicking "Export".

<Image align="center" alt="Any filters will be applied to the payment report export" border={false} caption="Any filters will be applied to the payment report export" src="https://files.readme.io/e0b19a453b9fcf11ee326f3ad7f27c45b02e0f9c40228287679e70bd87673100-rainforest_payment_report_export_filters.png" />

## Exported data

The generated CSV file will contain all the columns configured in the payment report component.

If the file will not contain any results, the modal will inform you and you may adjust your date range as needed and click "Export" again.