First Leeward

Simulation

Simulate clearing

POSThttps://api.firstleeward.com/v0/simulation/card-transactions/clearing

Simulates a clearing (settlement) event. Pass transactionId to clear an existing authorization, or omit to simulate offline/direct clearing.

Authorizations

Authorizationstring · headerrequired

API key as Bearer token, e.g. Bearer YOUR_API_KEY

Headers

Leeward-Versionenum<string>required

API version (YYYY-MM-DD). Available option: 2026-09-18

Body

application/json

cardIdstring<uuid>required

Card ID

transactionIdstring<uuid>

Existing transaction ID to clear. Omit to simulate offline/direct clearing (creates a new transaction).

amountnumberrequired

Merchant amount in the project's billing currency, before cardholder fees. Any FX markup or ATM fee that applies to the account is added on top, as in production, so the amount charged to the cardholder can be higher than this value.

originalAmountnumber

Amount in the original transaction currency. Must be provided together with originalCurrency, and is required when the event lands on a transaction whose original currency is not the billing currency.

originalCurrencystring

Original transaction currency as an ISO 4217 alpha code (e.g. EUR). Must be provided together with originalAmount.

Response

200Card transaction resource. The response shape varies by transaction status.
Option 1 · PendingCardTransaction
idstring<uuid>required

Card transaction identifier

accountIdstring<uuid>required

Account linked to the card

cardIdstring<uuid>required

Card used for this transaction

channelstringrequired

Transaction channel

Available options:ATMPOSECOMMERCEVISA_DIRECT
digitalWalletstring | nullrequired

Digital wallet used, or null if physical card

Available options:APPLE_PAYGOOGLE_PAYMERCHANT_TOKEN
originalCurrencystringrequired

Original transaction currency (merchant local currency)

currencystringrequired

Card currency

merchantobjectrequired

Merchant details

Show child attributes
idstring<uuid>required

Identifier of the merchant details recorded on this transaction. Not a stable merchant identifier: the same merchant has a different id on each transaction, so do not use it to identify or group merchants. Use cardAcceptorId instead.

cardAcceptorIdstring | nullrequired

Card acceptor ID (often called the merchant ID or MID), assigned by the merchant's acquirer and passed on by the card network. It is unique only within one acquirer, and one merchant can have several (for example one per terminal). Combine it with name, country, and mccCode when matching merchants. null when the network did not provide one.

namestringrequired

Merchant name

citystring | nullrequired

Merchant city

postCodestring | nullrequired

Merchant postal or ZIP code

statestring | nullrequired

Merchant state or province

countrystring

ISO 3166-1 alpha-2 country code

mccCodestringrequired

Merchant Category Code

mccCategorystringrequired

MCC category description

feesobjectrequired

Cardholder fee breakdown in the card billing currency. Always present; zeros when no fee applied.

Show child attributes
atmnumberrequired

ATM withdrawal markup charged to the cardholder (card currency)

fxnumberrequired

FX markup charged to the cardholder (card currency)

eventsobject[]required

Chronologically sorted lifecycle events (oldest first). Provides the full audit trail of what happened to this transaction.

Show child attributes
idstring<uuid>required

Event identifier

typestringrequired

Lifecycle event type. DISPUTE_REFUND is the credit from a card dispute resolved in favor of the cardholder; like REFUND it gives cleared value back to the cardholder.

Available options:AUTHORIZATIONCLEARINGREVERSALREFUNDDECLINEDISPUTE_REFUND
originalAmountnumberrequired

Event amount in the event-level original currency

originalCurrencystringrequired

Per-event original currency. Usually equals the parent transaction originalCurrency, but can differ when the card network reports a presentment (typically a clearing) in the bill currency instead of the merchant local currency.

amountnumberrequired

Event amount charged to the cardholder (card currency)

feesobjectrequired

Cardholder fee breakdown in the card billing currency. Always present; zeros when no fee applied.

Show child attributes
atmnumberrequired

ATM withdrawal markup charged to the cardholder (card currency)

fxnumberrequired

FX markup charged to the cardholder (card currency)

occurredAtstringrequired

ISO 8601 timestamp of when the event occurred

createdAtstringrequired

ISO 8601 timestamp of when the event was recorded

occurredAtstringrequired

ISO 8601 timestamp of when the transaction was initiated

createdAtstringrequired

ISO 8601 timestamp of creation

updatedAtstringrequired

ISO 8601 timestamp of last update

statusstringrequired
originalAmountobjectrequired

Amount breakdown showing authorized, reversed, and current values

Show child attributes
authorizednumberrequired

Original authorized amount before reversals

reversednumberrequired

Total amount reversed (credited back)

currentnumberrequired

Effective current amount (authorized - reversed, minimum 0)

amountobjectrequired

Amount breakdown showing authorized, reversed, and current values

Show child attributes
authorizednumberrequired

Original authorized amount before reversals

reversednumberrequired

Total amount reversed (credited back)

currentnumberrequired

Effective current amount (authorized - reversed, minimum 0)

conversionRatenumberrequired

Conversion rate from the original currency to the card currency

Option 2 · ClearedCardTransaction
idstring<uuid>required

Card transaction identifier

accountIdstring<uuid>required

Account linked to the card

cardIdstring<uuid>required

Card used for this transaction

channelstringrequired

Transaction channel

Available options:ATMPOSECOMMERCEVISA_DIRECT
digitalWalletstring | nullrequired

Digital wallet used, or null if physical card

Available options:APPLE_PAYGOOGLE_PAYMERCHANT_TOKEN
originalCurrencystringrequired

Original transaction currency (merchant local currency)

currencystringrequired

Card currency

merchantobjectrequired

Merchant details

Show child attributes
idstring<uuid>required

Identifier of the merchant details recorded on this transaction. Not a stable merchant identifier: the same merchant has a different id on each transaction, so do not use it to identify or group merchants. Use cardAcceptorId instead.

cardAcceptorIdstring | nullrequired

Card acceptor ID (often called the merchant ID or MID), assigned by the merchant's acquirer and passed on by the card network. It is unique only within one acquirer, and one merchant can have several (for example one per terminal). Combine it with name, country, and mccCode when matching merchants. null when the network did not provide one.

namestringrequired

Merchant name

citystring | nullrequired

Merchant city

postCodestring | nullrequired

Merchant postal or ZIP code

statestring | nullrequired

Merchant state or province

countrystring

ISO 3166-1 alpha-2 country code

mccCodestringrequired

Merchant Category Code

mccCategorystringrequired

MCC category description

feesobjectrequired

Cardholder fee breakdown in the card billing currency. Always present; zeros when no fee applied.

Show child attributes
atmnumberrequired

ATM withdrawal markup charged to the cardholder (card currency)

fxnumberrequired

FX markup charged to the cardholder (card currency)

eventsobject[]required

Chronologically sorted lifecycle events (oldest first). Provides the full audit trail of what happened to this transaction.

Show child attributes
idstring<uuid>required

Event identifier

typestringrequired

Lifecycle event type. DISPUTE_REFUND is the credit from a card dispute resolved in favor of the cardholder; like REFUND it gives cleared value back to the cardholder.

Available options:AUTHORIZATIONCLEARINGREVERSALREFUNDDECLINEDISPUTE_REFUND
originalAmountnumberrequired

Event amount in the event-level original currency

originalCurrencystringrequired

Per-event original currency. Usually equals the parent transaction originalCurrency, but can differ when the card network reports a presentment (typically a clearing) in the bill currency instead of the merchant local currency.

amountnumberrequired

Event amount charged to the cardholder (card currency)

feesobjectrequired

Cardholder fee breakdown in the card billing currency. Always present; zeros when no fee applied.

Show child attributes
atmnumberrequired

ATM withdrawal markup charged to the cardholder (card currency)

fxnumberrequired

FX markup charged to the cardholder (card currency)

occurredAtstringrequired

ISO 8601 timestamp of when the event occurred

createdAtstringrequired

ISO 8601 timestamp of when the event was recorded

occurredAtstringrequired

ISO 8601 timestamp of when the transaction was initiated

createdAtstringrequired

ISO 8601 timestamp of creation

updatedAtstringrequired

ISO 8601 timestamp of last update

statusstringrequired
originalAmountobjectrequired

Amount breakdown showing cleared, refunded, and current values

Show child attributes
clearednumberrequired

Total settled amount

refundednumberrequired

Total amount refunded, by the merchant (REFUND events) or through a dispute (DISPUTE_REFUND events)

currentnumberrequired

Effective current amount (cleared - refunded, minimum 0)

amountobjectrequired

Amount breakdown showing cleared, refunded, and current values

Show child attributes
clearednumberrequired

Total settled amount

refundednumberrequired

Total amount refunded, by the merchant (REFUND events) or through a dispute (DISPUTE_REFUND events)

currentnumberrequired

Effective current amount (cleared - refunded, minimum 0)

conversionRatenumberrequired

Conversion rate from the original currency to the card currency

Option 3 · DeclinedCardTransaction
idstring<uuid>required

Card transaction identifier

accountIdstring<uuid>required

Account linked to the card

cardIdstring<uuid>required

Card used for this transaction

channelstringrequired

Transaction channel

Available options:ATMPOSECOMMERCEVISA_DIRECT
digitalWalletstring | nullrequired

Digital wallet used, or null if physical card

Available options:APPLE_PAYGOOGLE_PAYMERCHANT_TOKEN
originalCurrencystringrequired

Original transaction currency (merchant local currency)

currencystringrequired

Card currency

merchantobjectrequired

Merchant details

Show child attributes
idstring<uuid>required

Identifier of the merchant details recorded on this transaction. Not a stable merchant identifier: the same merchant has a different id on each transaction, so do not use it to identify or group merchants. Use cardAcceptorId instead.

cardAcceptorIdstring | nullrequired

Card acceptor ID (often called the merchant ID or MID), assigned by the merchant's acquirer and passed on by the card network. It is unique only within one acquirer, and one merchant can have several (for example one per terminal). Combine it with name, country, and mccCode when matching merchants. null when the network did not provide one.

namestringrequired

Merchant name

citystring | nullrequired

Merchant city

postCodestring | nullrequired

Merchant postal or ZIP code

statestring | nullrequired

Merchant state or province

countrystring

ISO 3166-1 alpha-2 country code

mccCodestringrequired

Merchant Category Code

mccCategorystringrequired

MCC category description

feesobjectrequired

Cardholder fee breakdown in the card billing currency. Always present; zeros when no fee applied.

Show child attributes
atmnumberrequired

ATM withdrawal markup charged to the cardholder (card currency)

fxnumberrequired

FX markup charged to the cardholder (card currency)

eventsobject[]required

Chronologically sorted lifecycle events (oldest first). Provides the full audit trail of what happened to this transaction.

Show child attributes
idstring<uuid>required

Event identifier

typestringrequired

Lifecycle event type. DISPUTE_REFUND is the credit from a card dispute resolved in favor of the cardholder; like REFUND it gives cleared value back to the cardholder.

Available options:AUTHORIZATIONCLEARINGREVERSALREFUNDDECLINEDISPUTE_REFUND
originalAmountnumberrequired

Event amount in the event-level original currency

originalCurrencystringrequired

Per-event original currency. Usually equals the parent transaction originalCurrency, but can differ when the card network reports a presentment (typically a clearing) in the bill currency instead of the merchant local currency.

amountnumberrequired

Event amount charged to the cardholder (card currency)

feesobjectrequired

Cardholder fee breakdown in the card billing currency. Always present; zeros when no fee applied.

Show child attributes
atmnumberrequired

ATM withdrawal markup charged to the cardholder (card currency)

fxnumberrequired

FX markup charged to the cardholder (card currency)

occurredAtstringrequired

ISO 8601 timestamp of when the event occurred

createdAtstringrequired

ISO 8601 timestamp of when the event was recorded

occurredAtstringrequired

ISO 8601 timestamp of when the transaction was initiated

createdAtstringrequired

ISO 8601 timestamp of creation

updatedAtstringrequired

ISO 8601 timestamp of last update

statusstringrequired
originalAmountnumberrequired

Attempted transaction amount in the original currency

declineReasonobjectrequired

Reason the transaction was declined

Show child attributes
codestringrequired

Machine-readable decline reason code. Intended for client application logic (routing the cardholder to a top-up screen, prompting for PIN re-entry, ...). Do not display this string to cardholders directly; use message instead, or render your own copy keyed off code.

Available options:INSUFFICIENT_BALANCEINSUFFICIENT_MASTER_BALANCECARD_NOT_ACTIVECARD_NOT_ACTIVATEDCARD_EXPIREDCARD_FROZENCARD_BLOCKEDCARD_REPORTED_LOSTCARD_REPORTED_STOLENACCOUNT_NOT_ACTIVEINCORRECT_PININCORRECT_CVVINVALID_CARD_DETAILSCONTACTLESS_NOT_SUPPORTEDTERMINAL_ERRORCASH_SERVICE_NOT_AVAILABLEWITHDRAWALS_NOT_ALLOWEDATM_WITHDRAWAL_LIMIT_EXCEEDEDATM_WITHDRAWAL_FREQUENCY_EXCEEDEDMERCHANT_CARD_TYPE_MISMATCHMERCHANT_CATEGORY_CODE_NOT_ALLOWEDTRANSACTION_TYPE_NOT_ALLOWEDMERCHANT_NOT_ALLOWEDCHANNEL_NOT_ALLOWEDTRANSACTION_AMOUNT_LIMIT_EXCEEDEDSPEND_LIMIT_EXCEEDEDAUTHORIZATION_COUNT_LIMIT_EXCEEDEDTRANSACTION_NOT_ALLOWEDNETWORK_DECLINESUSPECTED_FRAUDINTERNAL_ERROR
messagestringrequired

Cardholder-facing description of the decline reason. Safe to render directly in your UI as a sensible default.

policyobject | nullrequired

The policy that caused the decline, or null if the transaction was declined for another reason (e.g. insufficient funds).

Show child attributes
idstringrequired

ID of the policy that declined the transaction. A UUID for your policies; a stable identifier for platform policies.

typestringrequired
Available options:MERCHANT_RESTRICTIONCHANNEL_RESTRICTIONTRANSACTION_AMOUNT_LIMITSPEND_LIMITAUTHORIZATION_COUNT_LIMIT
scopeTypestringrequired

The level the policy was attached to.

Available options:PROJECTUSERCARD
namestringrequired

Human-readable label.

Option 4 · VoidCardTransaction
idstring<uuid>required

Card transaction identifier

accountIdstring<uuid>required

Account linked to the card

cardIdstring<uuid>required

Card used for this transaction

channelstringrequired

Transaction channel

Available options:ATMPOSECOMMERCEVISA_DIRECT
digitalWalletstring | nullrequired

Digital wallet used, or null if physical card

Available options:APPLE_PAYGOOGLE_PAYMERCHANT_TOKEN
originalCurrencystringrequired

Original transaction currency (merchant local currency)

currencystringrequired

Card currency

merchantobjectrequired

Merchant details

Show child attributes
idstring<uuid>required

Identifier of the merchant details recorded on this transaction. Not a stable merchant identifier: the same merchant has a different id on each transaction, so do not use it to identify or group merchants. Use cardAcceptorId instead.

cardAcceptorIdstring | nullrequired

Card acceptor ID (often called the merchant ID or MID), assigned by the merchant's acquirer and passed on by the card network. It is unique only within one acquirer, and one merchant can have several (for example one per terminal). Combine it with name, country, and mccCode when matching merchants. null when the network did not provide one.

namestringrequired

Merchant name

citystring | nullrequired

Merchant city

postCodestring | nullrequired

Merchant postal or ZIP code

statestring | nullrequired

Merchant state or province

countrystring

ISO 3166-1 alpha-2 country code

mccCodestringrequired

Merchant Category Code

mccCategorystringrequired

MCC category description

feesobjectrequired

Cardholder fee breakdown in the card billing currency. Always present; zeros when no fee applied.

Show child attributes
atmnumberrequired

ATM withdrawal markup charged to the cardholder (card currency)

fxnumberrequired

FX markup charged to the cardholder (card currency)

eventsobject[]required

Chronologically sorted lifecycle events (oldest first). Provides the full audit trail of what happened to this transaction.

Show child attributes
idstring<uuid>required

Event identifier

typestringrequired

Lifecycle event type. DISPUTE_REFUND is the credit from a card dispute resolved in favor of the cardholder; like REFUND it gives cleared value back to the cardholder.

Available options:AUTHORIZATIONCLEARINGREVERSALREFUNDDECLINEDISPUTE_REFUND
originalAmountnumberrequired

Event amount in the event-level original currency

originalCurrencystringrequired

Per-event original currency. Usually equals the parent transaction originalCurrency, but can differ when the card network reports a presentment (typically a clearing) in the bill currency instead of the merchant local currency.

amountnumberrequired

Event amount charged to the cardholder (card currency)

feesobjectrequired

Cardholder fee breakdown in the card billing currency. Always present; zeros when no fee applied.

Show child attributes
atmnumberrequired

ATM withdrawal markup charged to the cardholder (card currency)

fxnumberrequired

FX markup charged to the cardholder (card currency)

occurredAtstringrequired

ISO 8601 timestamp of when the event occurred

createdAtstringrequired

ISO 8601 timestamp of when the event was recorded

occurredAtstringrequired

ISO 8601 timestamp of when the transaction was initiated

createdAtstringrequired

ISO 8601 timestamp of creation

updatedAtstringrequired

ISO 8601 timestamp of last update

statusstringrequired
originalAmountobjectrequired

Amount breakdown showing authorized, reversed, and current values

Show child attributes
authorizednumberrequired

Original authorized amount before reversals

reversednumberrequired

Total amount reversed (credited back)

currentnumberrequired

Effective current amount (authorized - reversed, minimum 0)

amountobjectrequired

Amount breakdown showing authorized, reversed, and current values

Show child attributes
authorizednumberrequired

Original authorized amount before reversals

reversednumberrequired

Total amount reversed (credited back)

currentnumberrequired

Effective current amount (authorized - reversed, minimum 0)

400The resource is not in a valid state for the requested simulation
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
404Response for status 404
Option 1 · CardNotFoundError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired
Option 2 · CardTransactionNotFoundError
errorobjectrequired
Show child attributes
codestringrequired
messagestringrequired
detailobject | nullrequired