Recipes

Simulating a Card Purchase

Create a purchase, settle it, and read back the result.

This walks through simulating a card purchase end to end: creating it, settling it, and confirming the outcome. See Simulation Scenarios first if the endpoints and event names are new.

All requests go to Penny Simulation (https://simulate.sandbox.api.thepennyinc.com).

Prerequisites

You need an active Sandbox card funded by a Capital Account with enough available balance for the purchase. Simulation does not create them. Create the Capital Account on Penny Banking, fund it with a simulated inbound payment from a linked account (POST /transaction/payment with "settle": true), and issue the card with Issuing a Card. The card must belong to the business you authenticate as.

1. Create the purchase

POST /transaction/card runs the simulated purchase through Penny’s authorization — account and card eligibility, available funds, spend controls, and any configured live decisioning callback — and the simulator confirms the result the way a card network would. A decline is still a successful response that contains a declined transaction.

curl -X POST https://simulate.sandbox.api.thepennyinc.com/transaction/card \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: 3f29c1a2-8b7e-4e51-9a2e-2b6a1c9d7e10" \
  -H "Content-Type: application/json" \
  -d '{
    "card_id": "card_01937f5d-a015-7a55-818b-a015a5518b97",
    "amount": "120.00",
    "currency": "USD",
    "merchant": {
      "merchant_id": "simulated-store-001",
      "name": "Simulator grocery store",
      "category_code": "5411",
      "city": "New York",
      "zip_code": "10001",
      "country": "US",
      "subdivision": "US-NY"
    },
    "acquirer": {"id": "simulated-acquirer", "name": "Simulator Acquiring Bank"}
  }'

Every following event call targets the response’s transaction_id. Store it.

Add "force": true to skip authorization and record the purchase as settled, modeling an offline or store-and-forward capture. You cannot request a specific decision: without force, the outcome is whatever Penny’s authorization decides. To test a decline, configure a spend control that the purchase breaks.

2. Settle it

curl -X POST https://simulate.sandbox.api.thepennyinc.com/transaction/update \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: 6c1e2a9d-2b6a-4c9d-9a2e-8b7e4e519a2e" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "'"$TRANSACTION_ID"'",
    "event": "transaction.settled",
    "amount": "120.00"
  }'

Settlement amounts are deltas, not cumulative totals. To exercise a multi-part settlement, send several transaction.settled events, each with its own Idempotency-Key and a partial amount (for example, "80.00" and then "40.00").

3. Confirm it

Read the simulated transaction through Penny Banking’s transaction endpoint:

curl https://sandbox.api.thepennyinc.com/transactions/$TRANSACTION_ID \
  -H "Authorization: Bearer $ACCESS_TOKEN"

See Transactions for its shape and Reading Transactions & Ledger Entries for how to find and reconcile it with other Sandbox transaction activity.

Next steps