Simulate a card transaction | The Penny Inc

curl -X POST https://simulate.sandbox.api.thepennyinc.com/transaction/card \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "card_id": "card_019375de-a2a0-7f31-884a-a2a0f3184abd",
  "amount": "25.00",
  "currency": "USD",
  "merchant": {
    "name": "Whole Foods Market",
    "category_code": "5411"
  },
  "acquirer": {
    "id": "acq_01j8xyzabc"
  }
}'

{
  "transaction_id": "transaction_01937a7d-ad6b-77ca-8046-ad6b7ca046ce",
  "account_id": "account_019372e3-b8dc-7de2-80b6-b8dcde20b6c9",
  "business_id": "business_01937b95-484e-75af-8c68-484e5afc68d3",
  "business_entity_id": "business_entity_01937c9d-3a1e-72b0-8881-3a1e2b088159",
  "program_id": "program_019377de-7f88-7f02-894f-7f88f0294fcb",
  "version": 1,
  "version_time": "2024-01-15T10:30:00Z",
  "stage": 2,
  "stage_time": "2024-01-15T10:30:00Z",
  "status": "approved",
  "direction": "outbound",
  "type": "payment",
  "base_amount": "108.50",
  "base_amount_currency": "USD",
  "channel": {
    "card_id": "card_019375de-a2a0-7f31-884a-a2a0f3184abd",
    "cardholder_id": "cardholder_01937e19-4ebb-75bd-8250-4ebb5bd25085",
    "processing_details": {
      "card_class": "consumer",
      "card_product_id": "card_product_01937f5d-a015-7a55-818b-a015a5518b97",
      "pan_entry_mode": "contactless",
      "type": "point_of_service"
    },
    "scheme_details": {
      "funding_type": "prepaid",
      "network": "visa",
      "product_type": "consumer"
    },
    "type": "card"
  },
  "counterparty": {
    "acquirer": {
      "id": "acq_01j8xyzabc",
      "name": "First National Merchant Services"
    },
    "merchant": {
      "category": "Grocery Stores, Supermarkets",
      "city": "San Francisco",
      "code": "5411",
      "country": "US",
      "merchant_id": "WFM-0481726",
      "name": "Whole Foods Market",
      "subdivision": "US-CA",
      "zip_code": "94105"
    },
    "type": "card"
  },
  "message": "Card payment approved",
  "client_reference": "payroll-run-2026-09-invoice-4471",
  "original_amount": "100.00",
  "original_amount_currency": "EUR"
}

Simulate a card purchase at a merchant. The purchase is authorized against the card’s balance and spend controls unless force is true.

Required permissions: simulation:execute.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Headers

Idempotency-Keystring or nullOptional1-255 characters

A unique key you generate, such as a UUID, so a retried request is applied only once. Optional but strongly advised. Penny keeps each key for 7 days per business and operation: a retry with the same key and body returns the original result, the same key with a different body returns 422, and a retry while the original request is still processing returns 409. Maximum 255 characters.

Request

This endpoint expects an object.

card_idstringRequired

The card making the purchase.

amountdouble or stringRequired

Decimal string in major units, e.g. “25.00” for $25.00; must be greater than zero.

currencyenumRequired

The ISO 4217 currency of amount. Must match the card’s funding currency.

Allowed values:

merchantobjectRequired

The merchant the card is used at.

acquirerobjectRequired

The acquirer submitting the transaction on the merchant's behalf.

forcebooleanOptionalDefaults to false

When true, skip authorization and record the purchase as settled, like an offline capture. When false, the purchase is authorized against the card's balance and spend controls first.

Response

The card transaction.

transaction_idstring

The unique identifier Penny assigns to this transaction.

account_idstring

The unique identifier of the account affected by this transaction.

business_idstring

The unique identifier of the business this transaction belongs to.

business_entity_idstring

The unique identifier of the business entity this transaction belongs to.

program_idstring

The unique identifier of the program this transaction belongs to.

versioninteger

The revision number within the current processing stage. It starts at 1 when the transaction enters a stage and increases when the record is updated without advancing to the next stage.

version_timedatetime

The date and time this revision was recorded.

stageinteger

The transaction's processing step number. It increases when a new event advances the transaction through its lifecycle.

stage_timedatetime

The date and time the transaction entered its current stage.

statusenum

The current lifecycle status of the transaction.

directionenum

Whether funds move into (inbound) or out of (outbound) the account.

Allowed values:

typeenum

The client-visible category of the transaction.

Allowed values:

base_amountstringformat: "^-?\d+(\.\d+)?$"

The transaction amount in the account's settlement currency.

base_amount_currencyenum

The three-letter ISO 4217 currency code of the settlement amount.

Allowed values:

channelobject

How the transaction was conducted.

counterpartyobject

The party on the opposite side of the transaction.

messagestring or nullOptional

Additional context about the current status, when available.

client_referencestring or nullOptional

Your own reference for this transaction, as supplied when the underlying movement was initiated. Penny stores it and never interprets it, and it can be used to look this transaction up. Present only where a reference was supplied.

original_amountstring or nullOptionalformat: "^-?\d+(\.\d+)?$"

The amount in the currency in which the transaction was presented. Present when that currency differs from the settlement currency.

original_amount_currencyenum or nullOptional

The three-letter ISO 4217 currency code of the presented amount. Present together with original_amount.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

422

Unprocessable Entity Error

429

Too Many Requests Error

500

Internal Server Error