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 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 to create an auth hold on the card.

1// Sim auth body example
2{
3  "amount": 100.00,
4  "association": "visa",
5  "merchant_name": "Testing Transactions" --> length needs to greater than 5
6}

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

1// Sim settlement body example
2{
3  "auth_id": "<auth_id_from_auth_response>",
4  "settle_amount": 100.00
5}

Best Practices

  • Validate your webhook handling against all possible transaction states