# Braintree

SureCloud connects to Braintree to retrieve merchant account configuration, user access records, and transaction processing settings. This allows SureCloud to verify that access to payment processing capabilities within Braintree is appropriately restricted, that account security settings are correctly configured, and that the integration is operating within the bounds required for PCI DSS compliance.

## Authentication and setup

Braintree authenticates API requests using a Merchant ID, Public Key, and Private Key. SureCloud uses credentials associated with a read-only Braintree user.

{% stepper %}
{% step %}

### Create a read-only user in Braintree

Log in to the Braintree Control Panel at [sandbox.braintreegateway.com](https://sandbox.braintreegateway.com/) (sandbox) or [www.braintreegateway.com](https://www.braintreegateway.com/) (production). Navigate to **Account → Team** and invite a new user (e.g. `surecloud@yourcompany.com`) with the **Read Only** role.
{% endstep %}

{% step %}

### Retrieve API credentials

Log in as the read-only user. Navigate to **Account → My User → View Authorizations** and note the **Merchant ID**, **Public Key**, and **Private Key** for the API credentials. Alternatively, an admin can generate API keys for the user from the Team page.
{% endstep %}

{% step %}

### Enter the credentials in SureCloud

Navigate to **SureCloud → Integrations → Braintree → Connect**. Select the environment (Production or Sandbox), enter the Merchant ID, Public Key, and Private Key. Click **Save** and then **Test Connection**.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
Store the Private Key securely. SureCloud encrypts it at rest, but treat it as a sensitive credential. Rotate it every 90 days and update it in **SureCloud → Integrations → Braintree → Edit Connection**.
{% endhint %}

## Endpoints

Braintree uses a GraphQL API for most data access. SureCloud uses the following queries:

| API Call                                    | Use Case                                                                                  |
| ------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `POST /graphql` — `ping` query              | Verify connection and credentials                                                         |
| `POST /graphql` — `search { transactions }` | Retrieve transaction records for payment data handling evidence                           |
| `POST /graphql` — `merchants` query         | Retrieve merchant account configuration                                                   |
| `POST /graphql` — `clientToken`             | Confirm tokenisation is configured (indirect evidence of cardholder data scope reduction) |

## Pagination

Braintree GraphQL search queries use cursor-based pagination. SureCloud uses the `pageInfo.endCursor` from each response as the `after` argument in the next query, continuing until `pageInfo.hasNextPage` is `false`.

```json
POST /graphql
{
  "query": "query { search { transactions(input: {}, first: 500, after: \"<cursor>\") { pageInfo { hasNextPage endCursor } edges { node { id status } } } } }"
}
```

## Required permissions

SureCloud requires a Braintree user with the **Read Only** role. This provides:

* Read access to transaction records
* Read access to merchant account configuration
* Read access to user and access settings

No refund, void, charge, or admin permissions are required.

## Polling frequency

| Data Type                      | Interval       |
| ------------------------------ | -------------- |
| Merchant account configuration | Every 24 hours |
| Transaction records            | Every 24 hours |

## Troubleshooting

<details>

<summary>Authentication fails with "Authentication Error"</summary>

One or more of the three credential values is incorrect, or the credentials are from the wrong environment (sandbox vs production). Confirm that the environment selected in SureCloud matches the credentials. Navigate to **Braintree → Account → My User → View Authorizations** to verify the Merchant ID and Public Key, and regenerate the Private Key if necessary.

</details>

<details>

<summary>Transaction search returns no results</summary>

Braintree transaction searches require a time range. SureCloud applies a rolling lookback window. If no transactions have been processed within the lookback window, the result will be empty. Confirm that transactions have been processed in production within the relevant time period.

</details>

<details>

<summary>Read-only user cannot access certain endpoints</summary>

Braintree's Read Only role restricts access to certain administrative endpoints. If SureCloud receives permission errors on specific queries, confirm the user role in **Braintree → Account → Team** and verify it is set to **Read Only**. Some Braintree configurations use custom roles — ensure the role includes all necessary read permissions.

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/braintree.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.