Getting Started

Penny provides APIs for building banking, card issuing, and financial infrastructure products.

You will typically work with:

• Penny Banking — accounts, transactions, ledger activity, businesses, access, and money movement.
• Penny Issuing — cardholders, cards, and card products.
• Penny Simulation — test supported transactions and external activity in Sandbox.

Banking and Issuing use the same authentication flow within an environment, so a single application access token can be used across both APIs subject to its permissions.

What you can build

With Penny you can:

• create and manage account structures;
• move funds between supported accounts;
• issue and manage cards;
• control spending through Spend Controls;
• read transactions and ledger activity;
• receive changes through webhooks;
• simulate supported financial activity before moving to Live.

If you are new to Penny’s resource model, start with Platform Concepts.

Before you start

You need access to the Penny Sandbox.

As part of onboarding, Penny provisions the initial access for your organization, including your first application credentials. Your administrator can then manage users, applications, roles, and permissions through the Access API. See Access Control.

Your application needs:

• a client ID;
• a client secret;
• the permissions required by the API operations you intend to use.

See Authentication and Environments.

1. Get an access token

Exchange your Sandbox application credentials for an OAuth 2.0 access token:

curl -X POST https://sandbox.api.thepennyinc.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
  }'

The response includes an access token:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 86400
}

Use it on subsequent requests:

Authorization: Bearer YOUR_ACCESS_TOKEN

See Authentication for the complete authentication flow.

2. Make your first API request

Once authenticated, make a read request. Retrieving your business profile works for every new Sandbox:

curl https://sandbox.api.thepennyinc.com/businesses/profile \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

A successful authenticated response confirms that:

• your credentials are valid;
• your access token works;
• you are calling the correct Sandbox environment;
• your application can access the requested API operation.

If you receive 403 Forbidden, your application is authenticated but does not have the required permission.

See Access Control.

3. Understand the resources you are building with

Each Platform Concepts page explains how one resource domain fits into the rest of Penny:

4. Build in Sandbox

Use Sandbox while developing and testing your integration.

Sandbox is isolated from Live and does not use your Live resources or credentials.

See Environments.

5. Simulate activity

Some financial activity originates outside your application — for example, a card authorization at a merchant or an incoming payment.

Use the Simulation API in Sandbox to drive supported test activity through Penny and verify how your integration responds.

This allows you to test:

• successful flows;
• transaction lifecycle updates;
• authorization behavior;
• webhook delivery;
• declines and failure scenarios.

Simulation is available in Sandbox only.

6. Handle failures safely

Before moving beyond basic requests, make sure your integration handles:

• authentication and permission errors;
• validation failures;
• asynchronous 202 Accepted operations;
• concurrent updates and 409 Conflict;
• safe retries and idempotency;
• 429 Too Many Requests;
• transient 5xx failures.

See:

• Errors & Rate Limits
• Retries & Idempotency
• Resource Versions & Concurrency

7. Subscribe to webhooks

Use webhooks to react to changes without continuously polling Penny.

Your integration should be able to:

• register a notification endpoint;
• complete endpoint verification;
• verify signed deliveries;
• handle retries and duplicate delivery safely.

See Webhooks Overview.

Moving to Live

Live access is provisioned separately from Sandbox.

Before production access is enabled, your organization must complete the applicable onboarding, agreements, compliance requirements, and integration-readiness process.

Live uses separate credentials and contains real financial and card data.

Build and validate your integration in Sandbox before moving to Live.