> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.upwardli.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.upwardli.com/_mcp/server.

# Funding & Simulating Transactions

# Overview

Upward provides APIs to **fund cards**, **simulate authorizations**, and **settle transactions** in a controlled environment.\
These capabilities make it possible to validate end-to-end payment flows without moving real money.

By using the sandbox, developers can:

* Fund test cards with virtual balances
* Simulate merchant authorizations (holds)
* Trigger settlements and declines
* Receive the same webhook events as production flows

---

## Funding a Card

You can programmatically load virtual balances onto a test card.\
This ensures you can test transactions with sufficient funds, edge cases like insufficient funds, or arbitrary balances for stress testing.
See [funding api](/api-access/api-reference/simulations/create-payment-card-sim-funding) to add funds. \

The token scope required to perform the action is `api:simulated-card:write`

**Example use cases:**

* Preload \$1,000 before running an authorization
* Test declines when no funds are available
* Reset balances between integration tests

---

## Simulating Authorizations

Authorizations represent the initial “hold” placed by a merchant.\
Using simulation APIs, you can generate authorization events for a given card with a specified amount.

**Key points:**

* Authorizations don’t immediately move money, but reduce available balance
* Responses include an `auth_id`
* Webhooks fire (e.g. `PaymentCard.Transaction.Auth`, `PaymentCard.Transaction.Archived`)
* The token scope required to perform the action is `api:simulated-card:write`

See [sim auth api](/api-access/api-reference/simulations/create-payment-card-sim-auth) to create an auth hold on the card.

```json
// Sim auth body example
{
  "amount": 100.00,
  "association": "visa",
  "merchant_name": "Testing Transactions" --> length needs to greater than 5
}
```

---

## Simulating Settlement

Settlements finalize authorizations by moving funds.\
In the sandbox, you can simulate full captures against an existing authorization.

**Key points:**

* Settlements reduce the account balance
* Webhooks fire (e.g. `PaymentCard.Transaction.Settlement`)

See [sim settlement api](/api-access/api-reference/simulations/create-payment-card-sim-settlement)

```json
// Sim settlement body example
{
  "auth_id": "<auth_id_from_auth_response>",
  "settle_amount": 100.00
}
```

---

## Best Practices

* Validate your webhook handling against all possible transaction states