Simulation
Simulate authorization
https://api.firstleeward.com/v0/simulation/card-transactions/authorizationSimulates a card authorization event. Creates a new PENDING transaction, or performs incremental authorization on an existing one. Checks the account balance and returns 400 if insufficient funds. Pass triggerFraudAlert: true to also raise a detected fraud alert against the charge.
Authorizations
Authorizationstring · headerrequiredAPI key as Bearer token, e.g. Bearer YOUR_API_KEY
Headers
Leeward-Versionenum<string>requiredAPI version (YYYY-MM-DD). Available option: 2026-09-18
Body
application/json
cardIdstring<uuid>requiredCard ID
transactionIdstring<uuid>Existing transaction ID for incremental authorization. Omit to create a new transaction.
amountnumberrequiredMerchant 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.
originalAmountnumberAmount 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.
originalCurrencystringOriginal transaction currency as an ISO 4217 alpha code (e.g. EUR). Must be provided together with originalAmount.
channelstringTransaction channel. Defaults to ECOMMERCE when omitted.
ATMPOSECOMMERCEVISA_DIRECTdigitalWalletstringDigital wallet type (e.g. APPLE_PAY, GOOGLE_PAY). Randomly generated if omitted.
APPLE_PAYGOOGLE_PAYMERCHANT_TOKENmerchantobjectMerchant details. All fields are optional; an omitted field is randomly generated, except country.
Show child attributes
namestringMerchant name
citystringMerchant city
postCodestringMerchant postal or ZIP code
statestringMerchant state or province
countrystringMerchant country (ISO 3166-1 alpha-2). Defaults to your card program's country, which makes the transaction domestic. Pass another country to charge an ATM withdrawal at the cross-border tier.
mccCodestringMerchant Category Code (4 digits)
mccCategorystringMCC category description
triggerFraudAlertbooleanWhen true, also raises a detected fraud alert against the resulting charge. The alert arrives asynchronously; wait for the CARD_FRAUD_ALERT_CREATED event. Detection alone does not block the card.
Response
200Card transaction resource. The response shape varies by transaction status.
Option 1 · PendingCardTransaction
idstring<uuid>requiredCard transaction identifier
accountIdstring<uuid>requiredAccount linked to the card
cardIdstring<uuid>requiredCard used for this transaction
channelstringrequiredTransaction channel
ATMPOSECOMMERCEVISA_DIRECTdigitalWalletstring | nullrequiredDigital wallet used, or null if physical card
APPLE_PAYGOOGLE_PAYMERCHANT_TOKENoriginalCurrencystringrequiredOriginal transaction currency (merchant local currency)
currencystringrequiredCard currency
merchantobjectrequiredMerchant details
Show child attributes
idstring<uuid>requiredIdentifier 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 | nullrequiredCard 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.
namestringrequiredMerchant name
citystring | nullrequiredMerchant city
postCodestring | nullrequiredMerchant postal or ZIP code
statestring | nullrequiredMerchant state or province
countrystringISO 3166-1 alpha-2 country code
mccCodestringrequiredMerchant Category Code
mccCategorystringrequiredMCC category description
feesobjectrequiredCardholder fee breakdown in the card billing currency. Always present; zeros when no fee applied.
Show child attributes
atmnumberrequiredATM withdrawal markup charged to the cardholder (card currency)
fxnumberrequiredFX markup charged to the cardholder (card currency)
eventsobject[]requiredChronologically sorted lifecycle events (oldest first). Provides the full audit trail of what happened to this transaction.
Show child attributes
idstring<uuid>requiredEvent identifier
typestringrequiredLifecycle 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.
AUTHORIZATIONCLEARINGREVERSALREFUNDDECLINEDISPUTE_REFUNDoriginalAmountnumberrequiredEvent amount in the event-level original currency
originalCurrencystringrequiredPer-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.
amountnumberrequiredEvent amount charged to the cardholder (card currency)
feesobjectrequiredCardholder fee breakdown in the card billing currency. Always present; zeros when no fee applied.
Show child attributes
atmnumberrequiredATM withdrawal markup charged to the cardholder (card currency)
fxnumberrequiredFX markup charged to the cardholder (card currency)
occurredAtstringrequiredISO 8601 timestamp of when the event occurred
createdAtstringrequiredISO 8601 timestamp of when the event was recorded
occurredAtstringrequiredISO 8601 timestamp of when the transaction was initiated
createdAtstringrequiredISO 8601 timestamp of creation
updatedAtstringrequiredISO 8601 timestamp of last update
statusstringrequiredoriginalAmountobjectrequiredAmount breakdown showing authorized, reversed, and current values
Show child attributes
authorizednumberrequiredOriginal authorized amount before reversals
reversednumberrequiredTotal amount reversed (credited back)
currentnumberrequiredEffective current amount (authorized - reversed, minimum 0)
amountobjectrequiredAmount breakdown showing authorized, reversed, and current values
Show child attributes
authorizednumberrequiredOriginal authorized amount before reversals
reversednumberrequiredTotal amount reversed (credited back)
currentnumberrequiredEffective current amount (authorized - reversed, minimum 0)
conversionRatenumberrequiredConversion rate from the original currency to the card currency
Option 2 · ClearedCardTransaction
idstring<uuid>requiredCard transaction identifier
accountIdstring<uuid>requiredAccount linked to the card
cardIdstring<uuid>requiredCard used for this transaction
channelstringrequiredTransaction channel
ATMPOSECOMMERCEVISA_DIRECTdigitalWalletstring | nullrequiredDigital wallet used, or null if physical card
APPLE_PAYGOOGLE_PAYMERCHANT_TOKENoriginalCurrencystringrequiredOriginal transaction currency (merchant local currency)
currencystringrequiredCard currency
merchantobjectrequiredMerchant details
Show child attributes
idstring<uuid>requiredIdentifier 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 | nullrequiredCard 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.
namestringrequiredMerchant name
citystring | nullrequiredMerchant city
postCodestring | nullrequiredMerchant postal or ZIP code
statestring | nullrequiredMerchant state or province
countrystringISO 3166-1 alpha-2 country code
mccCodestringrequiredMerchant Category Code
mccCategorystringrequiredMCC category description
feesobjectrequiredCardholder fee breakdown in the card billing currency. Always present; zeros when no fee applied.
Show child attributes
atmnumberrequiredATM withdrawal markup charged to the cardholder (card currency)
fxnumberrequiredFX markup charged to the cardholder (card currency)
eventsobject[]requiredChronologically sorted lifecycle events (oldest first). Provides the full audit trail of what happened to this transaction.
Show child attributes
idstring<uuid>requiredEvent identifier
typestringrequiredLifecycle 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.
AUTHORIZATIONCLEARINGREVERSALREFUNDDECLINEDISPUTE_REFUNDoriginalAmountnumberrequiredEvent amount in the event-level original currency
originalCurrencystringrequiredPer-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.
amountnumberrequiredEvent amount charged to the cardholder (card currency)
feesobjectrequiredCardholder fee breakdown in the card billing currency. Always present; zeros when no fee applied.
Show child attributes
atmnumberrequiredATM withdrawal markup charged to the cardholder (card currency)
fxnumberrequiredFX markup charged to the cardholder (card currency)
occurredAtstringrequiredISO 8601 timestamp of when the event occurred
createdAtstringrequiredISO 8601 timestamp of when the event was recorded
occurredAtstringrequiredISO 8601 timestamp of when the transaction was initiated
createdAtstringrequiredISO 8601 timestamp of creation
updatedAtstringrequiredISO 8601 timestamp of last update
statusstringrequiredoriginalAmountobjectrequiredAmount breakdown showing cleared, refunded, and current values
Show child attributes
clearednumberrequiredTotal settled amount
refundednumberrequiredTotal amount refunded, by the merchant (REFUND events) or through a dispute (DISPUTE_REFUND events)
currentnumberrequiredEffective current amount (cleared - refunded, minimum 0)
amountobjectrequiredAmount breakdown showing cleared, refunded, and current values
Show child attributes
clearednumberrequiredTotal settled amount
refundednumberrequiredTotal amount refunded, by the merchant (REFUND events) or through a dispute (DISPUTE_REFUND events)
currentnumberrequiredEffective current amount (cleared - refunded, minimum 0)
conversionRatenumberrequiredConversion rate from the original currency to the card currency
Option 3 · DeclinedCardTransaction
idstring<uuid>requiredCard transaction identifier
accountIdstring<uuid>requiredAccount linked to the card
cardIdstring<uuid>requiredCard used for this transaction
channelstringrequiredTransaction channel
ATMPOSECOMMERCEVISA_DIRECTdigitalWalletstring | nullrequiredDigital wallet used, or null if physical card
APPLE_PAYGOOGLE_PAYMERCHANT_TOKENoriginalCurrencystringrequiredOriginal transaction currency (merchant local currency)
currencystringrequiredCard currency
merchantobjectrequiredMerchant details
Show child attributes
idstring<uuid>requiredIdentifier 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 | nullrequiredCard 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.
namestringrequiredMerchant name
citystring | nullrequiredMerchant city
postCodestring | nullrequiredMerchant postal or ZIP code
statestring | nullrequiredMerchant state or province
countrystringISO 3166-1 alpha-2 country code
mccCodestringrequiredMerchant Category Code
mccCategorystringrequiredMCC category description
feesobjectrequiredCardholder fee breakdown in the card billing currency. Always present; zeros when no fee applied.
Show child attributes
atmnumberrequiredATM withdrawal markup charged to the cardholder (card currency)
fxnumberrequiredFX markup charged to the cardholder (card currency)
eventsobject[]requiredChronologically sorted lifecycle events (oldest first). Provides the full audit trail of what happened to this transaction.
Show child attributes
idstring<uuid>requiredEvent identifier
typestringrequiredLifecycle 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.
AUTHORIZATIONCLEARINGREVERSALREFUNDDECLINEDISPUTE_REFUNDoriginalAmountnumberrequiredEvent amount in the event-level original currency
originalCurrencystringrequiredPer-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.
amountnumberrequiredEvent amount charged to the cardholder (card currency)
feesobjectrequiredCardholder fee breakdown in the card billing currency. Always present; zeros when no fee applied.
Show child attributes
atmnumberrequiredATM withdrawal markup charged to the cardholder (card currency)
fxnumberrequiredFX markup charged to the cardholder (card currency)
occurredAtstringrequiredISO 8601 timestamp of when the event occurred
createdAtstringrequiredISO 8601 timestamp of when the event was recorded
occurredAtstringrequiredISO 8601 timestamp of when the transaction was initiated
createdAtstringrequiredISO 8601 timestamp of creation
updatedAtstringrequiredISO 8601 timestamp of last update
statusstringrequiredoriginalAmountnumberrequiredAttempted transaction amount in the original currency
declineReasonobjectrequiredReason the transaction was declined
Show child attributes
codestringrequiredMachine-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.
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_ERRORmessagestringrequiredCardholder-facing description of the decline reason. Safe to render directly in your UI as a sensible default.
policyobject | nullrequiredThe policy that caused the decline, or null if the transaction was declined for another reason (e.g. insufficient funds).
Show child attributes
idstringrequiredID of the policy that declined the transaction. A UUID for your policies; a stable identifier for platform policies.
typestringrequiredMERCHANT_RESTRICTIONCHANNEL_RESTRICTIONTRANSACTION_AMOUNT_LIMITSPEND_LIMITAUTHORIZATION_COUNT_LIMITscopeTypestringrequiredThe level the policy was attached to.
PROJECTUSERCARDnamestringrequiredHuman-readable label.
Option 4 · VoidCardTransaction
idstring<uuid>requiredCard transaction identifier
accountIdstring<uuid>requiredAccount linked to the card
cardIdstring<uuid>requiredCard used for this transaction
channelstringrequiredTransaction channel
ATMPOSECOMMERCEVISA_DIRECTdigitalWalletstring | nullrequiredDigital wallet used, or null if physical card
APPLE_PAYGOOGLE_PAYMERCHANT_TOKENoriginalCurrencystringrequiredOriginal transaction currency (merchant local currency)
currencystringrequiredCard currency
merchantobjectrequiredMerchant details
Show child attributes
idstring<uuid>requiredIdentifier 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 | nullrequiredCard 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.
namestringrequiredMerchant name
citystring | nullrequiredMerchant city
postCodestring | nullrequiredMerchant postal or ZIP code
statestring | nullrequiredMerchant state or province
countrystringISO 3166-1 alpha-2 country code
mccCodestringrequiredMerchant Category Code
mccCategorystringrequiredMCC category description
feesobjectrequiredCardholder fee breakdown in the card billing currency. Always present; zeros when no fee applied.
Show child attributes
atmnumberrequiredATM withdrawal markup charged to the cardholder (card currency)
fxnumberrequiredFX markup charged to the cardholder (card currency)
eventsobject[]requiredChronologically sorted lifecycle events (oldest first). Provides the full audit trail of what happened to this transaction.
Show child attributes
idstring<uuid>requiredEvent identifier
typestringrequiredLifecycle 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.
AUTHORIZATIONCLEARINGREVERSALREFUNDDECLINEDISPUTE_REFUNDoriginalAmountnumberrequiredEvent amount in the event-level original currency
originalCurrencystringrequiredPer-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.
amountnumberrequiredEvent amount charged to the cardholder (card currency)
feesobjectrequiredCardholder fee breakdown in the card billing currency. Always present; zeros when no fee applied.
Show child attributes
atmnumberrequiredATM withdrawal markup charged to the cardholder (card currency)
fxnumberrequiredFX markup charged to the cardholder (card currency)
occurredAtstringrequiredISO 8601 timestamp of when the event occurred
createdAtstringrequiredISO 8601 timestamp of when the event was recorded
occurredAtstringrequiredISO 8601 timestamp of when the transaction was initiated
createdAtstringrequiredISO 8601 timestamp of creation
updatedAtstringrequiredISO 8601 timestamp of last update
statusstringrequiredoriginalAmountobjectrequiredAmount breakdown showing authorized, reversed, and current values
Show child attributes
authorizednumberrequiredOriginal authorized amount before reversals
reversednumberrequiredTotal amount reversed (credited back)
currentnumberrequiredEffective current amount (authorized - reversed, minimum 0)
amountobjectrequiredAmount breakdown showing authorized, reversed, and current values
Show child attributes
authorizednumberrequiredOriginal authorized amount before reversals
reversednumberrequiredTotal amount reversed (credited back)
currentnumberrequiredEffective current amount (authorized - reversed, minimum 0)
400The resource is not in a valid state for the requested simulation
errorobjectrequiredShow child attributes
codestringrequiredmessagestringrequireddetailobject | nullrequired404Response for status 404
Option 1 · CardNotFoundError
errorobjectrequiredShow child attributes
codestringrequiredmessagestringrequireddetailobject | nullrequiredOption 2 · CardTransactionNotFoundError
errorobjectrequiredShow child attributes
codestringrequiredmessagestringrequireddetailobject | nullrequired409A simulation is already in progress for this card; wait for it to finish and retry
errorobjectrequiredShow child attributes
codestringrequiredmessagestringrequireddetailobject | nullrequired