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

​
Environments

Push Cash maintains two separate environments: 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
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 with the list of source IP addresses your backend uses to reach the API.
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.

​
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 whether it’s a duplicate by comparing the tag field in the request body against previous requests. Set the tag to your own internal identifier for the resource. If we detect a duplicate, we return the same response as the original request, and do not create the resource again.

​
Idempotency by Endpoint

​
Best Practices

  • Set the tag field to your internal identifier for the resource so that retries map back to the same record.
  • Use a unique tag for each new resource, and reuse the same tag when retrying a request.

​
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: