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

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

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