> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pushcash.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Concepts

This guide outlines important concepts to consider when developing an integration with the Push Cash API.

## Environments

Push Cash maintains two separate environments:

| Environment | Base URL                       | Purpose                           |
| ----------- | ------------------------------ | --------------------------------- |
| Sandbox     | `https://sandbox.pushcash.com` | Testing and development           |
| Production  | `https://api.pushcash.com`     | Live transactions with real funds |

Both environments expose the same API surface. Use the sandbox environment to build and test your integration before switching to production.

## Authentication

The API uses a persistent API key to authenticate requests.
Provide the key using the `Authorization` header with the value `Bearer YOUR_API_KEY`.
Requests that fail authentication return a `401` (Unauthorized) status code.

In order to test your API keys, you can make a request to the `/keys/verify` endpoint in either sandbox or production

```shell theme={null}
curl -X POST -H "Authorization: Bearer $APIKEY" https://sandbox.pushcash.com/keys/verify
```

If the API key is valid, the API will respond with a status code of `200` (OK) and the name of your organization

## IP Allowlisting

As an optional, additional layer of security, Push Cash can restrict access to your account so that **write requests** are only accepted from a set of source IP addresses that you specify. This protects your account even if an API key is leaked, since a stolen key cannot be used to move money from an unrecognized network.

IP allowlisting is configured by Push Cash during onboarding (or at any time afterward) — it is not self-serve. To enable it or change your allowlisted IPs, contact your Push Cash representative or [support](mailto:hello@pushcash.com) with the list of source IP addresses your backend uses to reach the API.

<Note>
  IP allowlisting applies **only to write operations** — `POST`, `PUT`, `PATCH`, and `DELETE` requests (for example, authorizing a payment or creating a user). Read operations (`GET`, `HEAD`) are **not** restricted and can be made from any IP address, so dashboards, monitoring, and reconciliation jobs continue to work without being added to the allowlist.
</Note>

### How it works

* You provide Push Cash with **one or more** source IP addresses. Multiple addresses are supported, which is useful when your traffic egresses from several NAT gateways or regions.
* When the feature is enabled, every write request is checked against your allowlist. The request must originate from one of the configured addresses.
* A write request from an IP that is **not** on the allowlist is rejected with a `403` (Forbidden) status code. Read requests are never blocked by this check.
* If no addresses are configured for your account, the check is skipped and all requests are allowed.

### Best practices

* Allowlist the **stable egress IPs** of your backend (for example, the public IPs of your NAT gateways or load balancers), not the IPs of individual servers that may change.
* Provide every egress IP your traffic can come from. If your platform scales across multiple gateways or availability zones, include all of them to avoid intermittent `403` rejections.
* Notify Push Cash **before** changing your network egress (for example, migrating regions or adding a new gateway) so your allowlist can be updated ahead of the cutover.

## Idempotency

Idempotency ensures that making the same request more than once won’t result in duplicate operations. This is helpful in cases like network retries or client timeouts.

When a `POST` request is received, we determine if it’s a duplicate by comparing one of the following:

* A **custom header** you provide (`X-Idempotency-Key`)
* A **unique field** in the request body (e.g. `tag`, `token`)
* The **exact contents** of the request body (if the same data was already processed)

If we detect a duplicate, we return the **same response as the original request**, and do **not** create  the resource again.

### Idempotency by Endpoint

| Endpoint          | Idempotency Mechanism | Description                                                  |
| ----------------- | --------------------- | ------------------------------------------------------------ |
| `POST /user`      | `tag` field           | Requests with the same `tag` return the same user.           |
| `POST /intent`    | `X-Idempotency-Key`   | Set this header to uniquely identify each request.           |
| `POST /authorize` | `token` field         | The `token` field prevents duplicate authorization attempts. |

### Best Practices

* Use a consistent `X-Idempotency-Key` when retrying requests.
* Ensure `tag` or `token` fields are unique for each new resource.
* Don’t reuse idempotency keys across different request types.

## Rate Limiting

The Push Cash API rate-limits requests to ensure stable and reliable service for all users.
All rate limits are evaluated on a sliding 1 minute window.
Requests subject to rate limiting will include the following response headers:

* `X-RateLimit-Limit`: The maximum number of requests that can be made to the endpoint in a window.
* `X-RateLimit-Remaining`: The number of requests remaining in the current window.
* `X-RateLimit-Reset`: The time at which the current window will reset.

When a request exceeds the rate limit, the API will respond with a status code of `429` (Too Many Requests).
Requests that are issued from your backend and authenticated with an API token are subject to the following rate limits:

| Operation | Examples                            | Limit                |
| --------- | ----------------------------------- | -------------------- |
| Write     | Authorizing payments                | 100 requests / min   |
| Read      | Getting or listing existing objects | 1,000 requests / min |