(Staging) Card Transaction Simulation

The endpoints described in this section are mock/utility APIs provided to help clients simulate end-to-end card transaction flows on the Shaype staging environment. They are designed to mimic the messages that Shaype would normally receive from Visa during a real cardholder transaction, so that your integration (account balance handling, webhook consumers, customer-facing UI, etc.) can be exercised without needing a physical card swipe at a merchant terminal.

🚧

Staging Only: These endpoints are available only in the Shaype staging environment. They are not exposed in production. Any attempt to call them in production will fail. They exist purely to support development, QA, integration testing, and end-to-end regression testing.

Before you begin

To use these endpoints you will need:

• A staging access with valid API credentials
• A **test customer with an active card **issued in staging (see Card Creation). The card's public token is required for every call.
• A linked account with sufficient balance for hold-based flows. If the balance is too low, the platform will decline the simulated authorisation, exactly as it would in production. To top up a staging account, use Create Credit Transaction for Account.
• A working webhook consumer, since the mock endpoints exercise the standard webhook delivery pipeline. If you don't yet have one, see Communications API (Webhooks).

Trigger mock ATM Card Transaction

• Generates a mock ATM cash withdrawal against a card on staging env. This simulates a Visa stand-in style message, that is, a card transaction that arrives at the platform without a separate authorisation hold step and is treated as already settled.
• Behaviour and resulting webhooks
  • A single transaction is created and immediately reflected on the account. The Shaype platform performs the same internal balance, limit, rule, and fraud checks it would for a live transaction, derives a transaction outcome, and emits a webhook with:
    • transactionType: CARD_TRANSACTION (settled in-line, no separate _SETTLED event)
    • isAtmTransaction: true
    • cardUsageDetails.isAtmWithdrawal: true
    • isPending: false

API definition: Trigger Mock ATM Card Transaction

Trigger mock card Hold

• Generates a mock authorisation hold request against a card. This simulates the first half of a typical card transaction lifecycle — the moment a merchant requests approval and Shaype rings-fences the funds — without a subsequent settlement.
• Behaviour and resulting webhooks
  • The Shaype platform runs its standard authorisation pipeline (balance check, limits, rules, fraud) and, if approved, increases the held balance and decreases the available balance on the account. A webhook is emitted with:
    • transactionType: CARD_TRANSACTION
    • isPending: true
    • holdHayId and transactionHayId set to the same value (the original hold ID)

API definition: Trigger Mock Card Hold

Trigger Mock Card Hold and Settlement

• Generates the most common card transaction flow: an authorisation hold followed automatically by a settlement (presentment / clearing) of that hold. This represents a normal merchant purchase that completes successfully end-to-end.

• Behaviour and resulting webhooks

  Two webhooks are emitted in sequence:

  • Authorisation hold: transactionType: CARD_TRANSACTION, isPending: true. Held balance increases, available balance decreases.
  • Settlement:- transactionType: CARD_TRANSACTION_SETTLED, isPending: false. The hold is released and the funds are removed from the total balance.

  • 📘

    The hold and settlement carry different transactionHayId values, but the settlement's holdHayId references the original hold so they can be tied together.

API definition: Trigger Mock Card Hold and Settlement

Trigger Mock Card Hold and Hold Update

• Generates a card transaction sequence that models a hold. The endpoint creates an initial authorisation hold, then applies an update, either an incremental authorisation (hold increase) or a partial/full reversal (hold decrease) and finally settles the resulting hold. This covers real-world scenarios common in hospitality, car rental, fuel, and hotel transactions.
• Param to consider

• Behaviour and resulting webhooks

  Two webhooks are emitted in sequence:

  1. Initial hold :- transactionType: CARD_TRANSACTION, isPending: true
  2. Hold update :-
     1. For an increase: transactionType: CARD_TRANSACTION, isPending: true. The webhook reports the updated total hold amount (original + increase). Both events share the same transactionHayId.
     2. For a reversal/decrease: transactionType: CARD_TRANSACTION_REFUND, isPending: true. Both events share the same transactionHayId.
  3. Settlement:- transactionType: CARD_TRANSACTION_SETTLED, isPending: false. The settlement carries its own transactionHayId and references the original hold via holdHayId.

API definition: Trigger Mock Card Hold and Hold Update

Trigger Mock Refund Card Transaction

• Generates a mock merchant-initiated refund crediting funds back to the cardholder. Unlike a hold reversal (which releases ring-fenced funds before settlement), a refund is a separate, post-settlement transaction that returns money to a customer who has already been charged.

• Behaviour and resulting webhooks

  A single webhook is emitted:

  • transactionType: CARD_TRANSACTION_REFUND
  • isPending: false (the refund settles immediately — there is no separate hold)
  • The refund carries its own transactionHayId it is not linked to a prior purchase by Shaype.

API definition: Trigger Mock Refund Card Transaction

Request Fields