> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reap.global/llms.txt
> Use this file to discover all available pages before exploring further.

# Simulate decline

> Simulates a declined card transaction. Creates a new `DECLINED` transaction, or declines an existing `PENDING` one.



## OpenAPI

````yaml /api-reference/openapi.json post /simulation/card-transactions/decline
openapi: 3.1.0
info:
  title: Reap API
  version: 1.0.0
  description: Reap platform API
servers:
  - url: https://sg.sandbox.api.reap.global
    description: Singapore sandbox
  - url: https://sg.prod.api.reap.global
    description: Singapore production
  - url: https://mx.sandbox.api.reap.global
    description: Mexico sandbox
  - url: https://mx.prod.api.reap.global
    description: Mexico production
  - url: https://sandbox.api.reap.global
    description: Singapore sandbox (alias)
  - url: https://prod.api.reap.global
    description: Singapore production (alias)
security:
  - bearerAuth: []
tags:
  - name: Accounts
  - name: Activities
  - name: Card Designs
  - name: Card Shipments
  - name: Card Transactions
  - name: Cards
  - name: Companies
  - name: Crypto Deposits
  - name: Crypto Withdrawals
  - name: Disputes
  - name: Fees
  - name: Fiat Deposits
  - name: Fraud Alerts
  - name: Policies
  - name: Simulation
  - name: Statements
  - name: Users
  - name: Virtual Asset Postings
  - name: Virtual Assets
  - name: Webhooks
  - name: Agentic
paths:
  /simulation/card-transactions/decline:
    post:
      tags:
        - Simulation
      summary: Simulate decline
      description: >-
        Simulates a declined card transaction. Creates a new `DECLINED`
        transaction, or declines an existing `PENDING` one.
      operationId: cardTransactionDecline_simulation
      parameters:
        - name: Reap-Version
          in: header
          required: true
          schema:
            type: string
            enum:
              - '2025-02-14'
            description: API version (YYYY-MM-DD)
            example: '2025-02-14'
      requestBody:
        description: Simulate a decline event on a card
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                cardId:
                  description: Card ID
                  type: string
                  format: uuid
                transactionId:
                  description: >-
                    Existing transaction ID. Omit to create a new declined
                    transaction.
                  type: string
                  format: uuid
                amount:
                  type: number
                  minimum: 0
                  examples:
                    - 100.5
                    - 0
                    - 1234.99
                  description: >-
                    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.
                originalAmount:
                  description: >-
                    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.
                  type: number
                  minimum: 0
                  examples:
                    - 100.5
                    - 0
                    - 1234.99
                originalCurrency:
                  description: >-
                    Original transaction currency as an ISO 4217 alpha code
                    (e.g. `EUR`). Must be provided together with
                    `originalAmount`.
                  type: string
                  pattern: ^[A-Z]{3}$
                channel:
                  description: Transaction channel. Defaults to `ECOMMERCE` when omitted.
                  type: string
                  enum:
                    - ATM
                    - POS
                    - ECOMMERCE
                    - VISA_DIRECT
                  example: ATM
                digitalWallet:
                  description: >-
                    Digital wallet type (e.g. `APPLE_PAY`, `GOOGLE_PAY`).
                    Randomly generated if omitted.
                  type: string
                  enum:
                    - APPLE_PAY
                    - GOOGLE_PAY
                    - MERCHANT_TOKEN
                  example: APPLE_PAY
                merchant:
                  type: object
                  properties:
                    name:
                      description: Merchant name
                      type: string
                      minLength: 1
                    city:
                      description: Merchant city
                      type: string
                      minLength: 1
                    postCode:
                      description: Merchant postal or ZIP code
                      type: string
                      minLength: 1
                    state:
                      description: Merchant state or province
                      type: string
                      minLength: 1
                    country:
                      description: >-
                        Merchant 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.
                      type: string
                      minLength: 2
                      maxLength: 2
                      examples:
                        - US
                        - GB
                        - DE
                    mccCode:
                      description: Merchant Category Code (4 digits)
                      type: string
                      minLength: 4
                      maxLength: 4
                    mccCategory:
                      description: MCC category description
                      type: string
                      minLength: 1
                  description: >-
                    Merchant details. All fields are optional; an omitted field
                    is randomly generated, except `country`.
                declineReason:
                  description: Decline reason code. Defaults to `INSUFFICIENT_BALANCE`.
                  type: string
                  enum:
                    - INSUFFICIENT_BALANCE
                    - INSUFFICIENT_MASTER_BALANCE
                    - CARD_NOT_ACTIVE
                    - CARD_NOT_ACTIVATED
                    - CARD_EXPIRED
                    - CARD_FROZEN
                    - CARD_BLOCKED
                    - CARD_REPORTED_LOST
                    - CARD_REPORTED_STOLEN
                    - ACCOUNT_NOT_ACTIVE
                    - INCORRECT_PIN
                    - INCORRECT_CVV
                    - INVALID_CARD_DETAILS
                    - CONTACTLESS_NOT_SUPPORTED
                    - TERMINAL_ERROR
                    - CASH_SERVICE_NOT_AVAILABLE
                    - WITHDRAWALS_NOT_ALLOWED
                    - ATM_WITHDRAWAL_LIMIT_EXCEEDED
                    - ATM_WITHDRAWAL_FREQUENCY_EXCEEDED
                    - MERCHANT_CARD_TYPE_MISMATCH
                    - MERCHANT_CATEGORY_CODE_NOT_ALLOWED
                    - TRANSACTION_TYPE_NOT_ALLOWED
                    - MERCHANT_NOT_ALLOWED
                    - CHANNEL_NOT_ALLOWED
                    - TRANSACTION_AMOUNT_LIMIT_EXCEEDED
                    - SPEND_LIMIT_EXCEEDED
                    - AUTHORIZATION_COUNT_LIMIT_EXCEEDED
                    - TRANSACTION_NOT_ALLOWED
                    - NETWORK_DECLINE
                    - SUSPECTED_FRAUD
                    - INTERNAL_ERROR
                  example: INSUFFICIENT_BALANCE
              required:
                - cardId
                - amount
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                cardId:
                  description: Card ID
                  type: string
                  format: uuid
                transactionId:
                  description: >-
                    Existing transaction ID. Omit to create a new declined
                    transaction.
                  type: string
                  format: uuid
                amount:
                  type: number
                  minimum: 0
                  examples:
                    - 100.5
                    - 0
                    - 1234.99
                  description: >-
                    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.
                originalAmount:
                  description: >-
                    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.
                  type: number
                  minimum: 0
                  examples:
                    - 100.5
                    - 0
                    - 1234.99
                originalCurrency:
                  description: >-
                    Original transaction currency as an ISO 4217 alpha code
                    (e.g. `EUR`). Must be provided together with
                    `originalAmount`.
                  type: string
                  pattern: ^[A-Z]{3}$
                channel:
                  description: Transaction channel. Defaults to `ECOMMERCE` when omitted.
                  type: string
                  enum:
                    - ATM
                    - POS
                    - ECOMMERCE
                    - VISA_DIRECT
                  example: ATM
                digitalWallet:
                  description: >-
                    Digital wallet type (e.g. `APPLE_PAY`, `GOOGLE_PAY`).
                    Randomly generated if omitted.
                  type: string
                  enum:
                    - APPLE_PAY
                    - GOOGLE_PAY
                    - MERCHANT_TOKEN
                  example: APPLE_PAY
                merchant:
                  type: object
                  properties:
                    name:
                      description: Merchant name
                      type: string
                      minLength: 1
                    city:
                      description: Merchant city
                      type: string
                      minLength: 1
                    postCode:
                      description: Merchant postal or ZIP code
                      type: string
                      minLength: 1
                    state:
                      description: Merchant state or province
                      type: string
                      minLength: 1
                    country:
                      description: >-
                        Merchant 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.
                      type: string
                      minLength: 2
                      maxLength: 2
                      examples:
                        - US
                        - GB
                        - DE
                    mccCode:
                      description: Merchant Category Code (4 digits)
                      type: string
                      minLength: 4
                      maxLength: 4
                    mccCategory:
                      description: MCC category description
                      type: string
                      minLength: 1
                  description: >-
                    Merchant details. All fields are optional; an omitted field
                    is randomly generated, except `country`.
                declineReason:
                  description: Decline reason code. Defaults to `INSUFFICIENT_BALANCE`.
                  type: string
                  enum:
                    - INSUFFICIENT_BALANCE
                    - INSUFFICIENT_MASTER_BALANCE
                    - CARD_NOT_ACTIVE
                    - CARD_NOT_ACTIVATED
                    - CARD_EXPIRED
                    - CARD_FROZEN
                    - CARD_BLOCKED
                    - CARD_REPORTED_LOST
                    - CARD_REPORTED_STOLEN
                    - ACCOUNT_NOT_ACTIVE
                    - INCORRECT_PIN
                    - INCORRECT_CVV
                    - INVALID_CARD_DETAILS
                    - CONTACTLESS_NOT_SUPPORTED
                    - TERMINAL_ERROR
                    - CASH_SERVICE_NOT_AVAILABLE
                    - WITHDRAWALS_NOT_ALLOWED
                    - ATM_WITHDRAWAL_LIMIT_EXCEEDED
                    - ATM_WITHDRAWAL_FREQUENCY_EXCEEDED
                    - MERCHANT_CARD_TYPE_MISMATCH
                    - MERCHANT_CATEGORY_CODE_NOT_ALLOWED
                    - TRANSACTION_TYPE_NOT_ALLOWED
                    - MERCHANT_NOT_ALLOWED
                    - CHANNEL_NOT_ALLOWED
                    - TRANSACTION_AMOUNT_LIMIT_EXCEEDED
                    - SPEND_LIMIT_EXCEEDED
                    - AUTHORIZATION_COUNT_LIMIT_EXCEEDED
                    - TRANSACTION_NOT_ALLOWED
                    - NETWORK_DECLINE
                    - SUSPECTED_FRAUD
                    - INTERNAL_ERROR
                  example: INSUFFICIENT_BALANCE
              required:
                - cardId
                - amount
          multipart/form-data:
            schema:
              type: object
              properties:
                cardId:
                  description: Card ID
                  type: string
                  format: uuid
                transactionId:
                  description: >-
                    Existing transaction ID. Omit to create a new declined
                    transaction.
                  type: string
                  format: uuid
                amount:
                  type: number
                  minimum: 0
                  examples:
                    - 100.5
                    - 0
                    - 1234.99
                  description: >-
                    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.
                originalAmount:
                  description: >-
                    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.
                  type: number
                  minimum: 0
                  examples:
                    - 100.5
                    - 0
                    - 1234.99
                originalCurrency:
                  description: >-
                    Original transaction currency as an ISO 4217 alpha code
                    (e.g. `EUR`). Must be provided together with
                    `originalAmount`.
                  type: string
                  pattern: ^[A-Z]{3}$
                channel:
                  description: Transaction channel. Defaults to `ECOMMERCE` when omitted.
                  type: string
                  enum:
                    - ATM
                    - POS
                    - ECOMMERCE
                    - VISA_DIRECT
                  example: ATM
                digitalWallet:
                  description: >-
                    Digital wallet type (e.g. `APPLE_PAY`, `GOOGLE_PAY`).
                    Randomly generated if omitted.
                  type: string
                  enum:
                    - APPLE_PAY
                    - GOOGLE_PAY
                    - MERCHANT_TOKEN
                  example: APPLE_PAY
                merchant:
                  type: object
                  properties:
                    name:
                      description: Merchant name
                      type: string
                      minLength: 1
                    city:
                      description: Merchant city
                      type: string
                      minLength: 1
                    postCode:
                      description: Merchant postal or ZIP code
                      type: string
                      minLength: 1
                    state:
                      description: Merchant state or province
                      type: string
                      minLength: 1
                    country:
                      description: >-
                        Merchant 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.
                      type: string
                      minLength: 2
                      maxLength: 2
                      examples:
                        - US
                        - GB
                        - DE
                    mccCode:
                      description: Merchant Category Code (4 digits)
                      type: string
                      minLength: 4
                      maxLength: 4
                    mccCategory:
                      description: MCC category description
                      type: string
                      minLength: 1
                  description: >-
                    Merchant details. All fields are optional; an omitted field
                    is randomly generated, except `country`.
                declineReason:
                  description: Decline reason code. Defaults to `INSUFFICIENT_BALANCE`.
                  type: string
                  enum:
                    - INSUFFICIENT_BALANCE
                    - INSUFFICIENT_MASTER_BALANCE
                    - CARD_NOT_ACTIVE
                    - CARD_NOT_ACTIVATED
                    - CARD_EXPIRED
                    - CARD_FROZEN
                    - CARD_BLOCKED
                    - CARD_REPORTED_LOST
                    - CARD_REPORTED_STOLEN
                    - ACCOUNT_NOT_ACTIVE
                    - INCORRECT_PIN
                    - INCORRECT_CVV
                    - INVALID_CARD_DETAILS
                    - CONTACTLESS_NOT_SUPPORTED
                    - TERMINAL_ERROR
                    - CASH_SERVICE_NOT_AVAILABLE
                    - WITHDRAWALS_NOT_ALLOWED
                    - ATM_WITHDRAWAL_LIMIT_EXCEEDED
                    - ATM_WITHDRAWAL_FREQUENCY_EXCEEDED
                    - MERCHANT_CARD_TYPE_MISMATCH
                    - MERCHANT_CATEGORY_CODE_NOT_ALLOWED
                    - TRANSACTION_TYPE_NOT_ALLOWED
                    - MERCHANT_NOT_ALLOWED
                    - CHANNEL_NOT_ALLOWED
                    - TRANSACTION_AMOUNT_LIMIT_EXCEEDED
                    - SPEND_LIMIT_EXCEEDED
                    - AUTHORIZATION_COUNT_LIMIT_EXCEEDED
                    - TRANSACTION_NOT_ALLOWED
                    - NETWORK_DECLINE
                    - SUSPECTED_FRAUD
                    - INTERNAL_ERROR
                  example: INSUFFICIENT_BALANCE
              required:
                - cardId
                - amount
      responses:
        '200':
          description: >-
            Card transaction resource. The response shape varies by transaction
            status.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/PendingCardTransaction'
                    title: Pending
                  - $ref: '#/components/schemas/ClearedCardTransaction'
                    title: Cleared
                  - $ref: '#/components/schemas/DeclinedCardTransaction'
                    title: Declined
                  - $ref: '#/components/schemas/VoidCardTransaction'
                    title: Void
        '400':
          description: The resource is not in a valid state for the requested simulation
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: SIMULATION_INVALID_STATE
                      message:
                        type: string
                      detail:
                        anyOf:
                          - type: object
                            additionalProperties: {}
                          - type: 'null'
                    required:
                      - code
                      - message
                      - detail
                required:
                  - error
                title: SimulationInvalidStateError
        '404':
          description: Response for status 404
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: CARD_NOT_FOUND
                          message:
                            type: string
                          detail:
                            anyOf:
                              - type: object
                                additionalProperties: {}
                              - type: 'null'
                        required:
                          - code
                          - message
                          - detail
                    required:
                      - error
                    title: CardNotFoundError
                    description: Card not found
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            const: CARD_TRANSACTION_NOT_FOUND
                          message:
                            type: string
                          detail:
                            anyOf:
                              - type: object
                                additionalProperties: {}
                              - type: 'null'
                        required:
                          - code
                          - message
                          - detail
                    required:
                      - error
                    title: CardTransactionNotFoundError
                    description: Card transaction not found
        '409':
          description: >-
            A simulation is already in progress for this card; wait for it to
            finish and retry
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        const: SIMULATION_IN_PROGRESS
                      message:
                        type: string
                      detail:
                        anyOf:
                          - type: object
                            additionalProperties: {}
                          - type: 'null'
                    required:
                      - code
                      - message
                      - detail
                required:
                  - error
                title: SimulationInProgressError
components:
  schemas:
    PendingCardTransaction:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Card transaction identifier
        accountId:
          type: string
          format: uuid
          description: Account linked to the card
        cardId:
          type: string
          format: uuid
          description: Card used for this transaction
        channel:
          type: string
          enum:
            - ATM
            - POS
            - ECOMMERCE
            - VISA_DIRECT
          description: Transaction channel
          example: ATM
        digitalWallet:
          anyOf:
            - type: string
              enum:
                - APPLE_PAY
                - GOOGLE_PAY
                - MERCHANT_TOKEN
              example: APPLE_PAY
            - type: 'null'
          description: Digital wallet used, or null if physical card
        originalCurrency:
          type: string
          examples:
            - USD
            - HKD
            - EUR
          description: Original transaction currency (merchant local currency)
        currency:
          type: string
          examples:
            - USD
            - HKD
            - EUR
          description: Card currency
        merchant:
          $ref: '#/components/schemas/CardTransactionMerchant'
        fees:
          $ref: '#/components/schemas/CardTransactionFees'
          description: >-
            Net cardholder fees in the card currency (same aggregation legs as
            cardholder amount for PENDING/VOID/CLEARED; decline-event fees for
            DECLINED)
        events:
          type: array
          items:
            $ref: '#/components/schemas/TransactionEvent'
          description: >-
            Chronologically sorted lifecycle events (oldest first). Provides the
            full audit trail of what happened to this transaction.
        occurredAt:
          type: string
          examples:
            - '2024-01-15T10:30:00Z'
          description: ISO 8601 timestamp of when the transaction was initiated
        createdAt:
          type: string
          examples:
            - '2024-01-15T10:30:00Z'
          description: ISO 8601 timestamp of creation
        updatedAt:
          type: string
          examples:
            - '2024-01-15T10:35:00Z'
          description: ISO 8601 timestamp of last update
        status:
          type: string
          const: PENDING
        originalAmount:
          $ref: '#/components/schemas/AmountBreakdown'
          description: Amount in the original transaction currency
        amount:
          $ref: '#/components/schemas/AmountBreakdown'
          description: Amount charged to the cardholder
        conversionRate:
          type: number
          minimum: 0
          examples:
            - 1
            - 0.128205
            - 7.812
          description: Conversion rate from the original currency to the card currency
      required:
        - id
        - accountId
        - cardId
        - channel
        - digitalWallet
        - originalCurrency
        - currency
        - merchant
        - fees
        - events
        - occurredAt
        - createdAt
        - updatedAt
        - status
        - originalAmount
        - amount
        - conversionRate
      description: Authorized transaction that hasn't settled yet
    ClearedCardTransaction:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Card transaction identifier
        accountId:
          type: string
          format: uuid
          description: Account linked to the card
        cardId:
          type: string
          format: uuid
          description: Card used for this transaction
        channel:
          type: string
          enum:
            - ATM
            - POS
            - ECOMMERCE
            - VISA_DIRECT
          description: Transaction channel
          example: ATM
        digitalWallet:
          anyOf:
            - type: string
              enum:
                - APPLE_PAY
                - GOOGLE_PAY
                - MERCHANT_TOKEN
              example: APPLE_PAY
            - type: 'null'
          description: Digital wallet used, or null if physical card
        originalCurrency:
          type: string
          examples:
            - USD
            - HKD
            - EUR
          description: Original transaction currency (merchant local currency)
        currency:
          type: string
          examples:
            - USD
            - HKD
            - EUR
          description: Card currency
        merchant:
          $ref: '#/components/schemas/CardTransactionMerchant'
        fees:
          $ref: '#/components/schemas/CardTransactionFees'
          description: >-
            Net cardholder fees in the card currency (same aggregation legs as
            cardholder amount for PENDING/VOID/CLEARED; decline-event fees for
            DECLINED)
        events:
          type: array
          items:
            $ref: '#/components/schemas/TransactionEvent'
          description: >-
            Chronologically sorted lifecycle events (oldest first). Provides the
            full audit trail of what happened to this transaction.
        occurredAt:
          type: string
          examples:
            - '2024-01-15T10:30:00Z'
          description: ISO 8601 timestamp of when the transaction was initiated
        createdAt:
          type: string
          examples:
            - '2024-01-15T10:30:00Z'
          description: ISO 8601 timestamp of creation
        updatedAt:
          type: string
          examples:
            - '2024-01-15T10:35:00Z'
          description: ISO 8601 timestamp of last update
        status:
          type: string
          const: CLEARED
        originalAmount:
          $ref: '#/components/schemas/ClearedAmountBreakdown'
          description: Amount in the original transaction currency
        amount:
          $ref: '#/components/schemas/ClearedAmountBreakdown'
          description: Amount charged to the cardholder
        conversionRate:
          type: number
          minimum: 0
          examples:
            - 1
            - 0.128205
            - 7.812
          description: Conversion rate from the original currency to the card currency
      required:
        - id
        - accountId
        - cardId
        - channel
        - digitalWallet
        - originalCurrency
        - currency
        - merchant
        - fees
        - events
        - occurredAt
        - createdAt
        - updatedAt
        - status
        - originalAmount
        - amount
        - conversionRate
      description: Fully settled transaction
    DeclinedCardTransaction:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Card transaction identifier
        accountId:
          type: string
          format: uuid
          description: Account linked to the card
        cardId:
          type: string
          format: uuid
          description: Card used for this transaction
        channel:
          type: string
          enum:
            - ATM
            - POS
            - ECOMMERCE
            - VISA_DIRECT
          description: Transaction channel
          example: ATM
        digitalWallet:
          anyOf:
            - type: string
              enum:
                - APPLE_PAY
                - GOOGLE_PAY
                - MERCHANT_TOKEN
              example: APPLE_PAY
            - type: 'null'
          description: Digital wallet used, or null if physical card
        originalCurrency:
          type: string
          examples:
            - USD
            - HKD
            - EUR
          description: Original transaction currency (merchant local currency)
        currency:
          type: string
          examples:
            - USD
            - HKD
            - EUR
          description: Card currency
        merchant:
          $ref: '#/components/schemas/CardTransactionMerchant'
        fees:
          $ref: '#/components/schemas/CardTransactionFees'
          description: >-
            Net cardholder fees in the card currency (same aggregation legs as
            cardholder amount for PENDING/VOID/CLEARED; decline-event fees for
            DECLINED)
        events:
          type: array
          items:
            $ref: '#/components/schemas/TransactionEvent'
          description: >-
            Chronologically sorted lifecycle events (oldest first). Provides the
            full audit trail of what happened to this transaction.
        occurredAt:
          type: string
          examples:
            - '2024-01-15T10:30:00Z'
          description: ISO 8601 timestamp of when the transaction was initiated
        createdAt:
          type: string
          examples:
            - '2024-01-15T10:30:00Z'
          description: ISO 8601 timestamp of creation
        updatedAt:
          type: string
          examples:
            - '2024-01-15T10:35:00Z'
          description: ISO 8601 timestamp of last update
        status:
          type: string
          const: DECLINED
        originalAmount:
          type: number
          minimum: 0
          examples:
            - 100.5
            - 0
            - 1234.99
          description: Attempted transaction amount in the original currency
        declineReason:
          $ref: '#/components/schemas/DeclineReason'
        policy:
          anyOf:
            - $ref: '#/components/schemas/DeclinedPolicy'
              title: DeclinedPolicy
            - type: 'null'
          description: >-
            The policy that caused the decline, or null if the transaction was
            declined for another reason (e.g. insufficient funds).
      required:
        - id
        - accountId
        - cardId
        - channel
        - digitalWallet
        - originalCurrency
        - currency
        - merchant
        - fees
        - events
        - occurredAt
        - createdAt
        - updatedAt
        - status
        - originalAmount
        - declineReason
        - policy
      description: Transaction that was declined during authorization
    VoidCardTransaction:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Card transaction identifier
        accountId:
          type: string
          format: uuid
          description: Account linked to the card
        cardId:
          type: string
          format: uuid
          description: Card used for this transaction
        channel:
          type: string
          enum:
            - ATM
            - POS
            - ECOMMERCE
            - VISA_DIRECT
          description: Transaction channel
          example: ATM
        digitalWallet:
          anyOf:
            - type: string
              enum:
                - APPLE_PAY
                - GOOGLE_PAY
                - MERCHANT_TOKEN
              example: APPLE_PAY
            - type: 'null'
          description: Digital wallet used, or null if physical card
        originalCurrency:
          type: string
          examples:
            - USD
            - HKD
            - EUR
          description: Original transaction currency (merchant local currency)
        currency:
          type: string
          examples:
            - USD
            - HKD
            - EUR
          description: Card currency
        merchant:
          $ref: '#/components/schemas/CardTransactionMerchant'
        fees:
          $ref: '#/components/schemas/CardTransactionFees'
          description: >-
            Net cardholder fees in the card currency (same aggregation legs as
            cardholder amount for PENDING/VOID/CLEARED; decline-event fees for
            DECLINED)
        events:
          type: array
          items:
            $ref: '#/components/schemas/TransactionEvent'
          description: >-
            Chronologically sorted lifecycle events (oldest first). Provides the
            full audit trail of what happened to this transaction.
        occurredAt:
          type: string
          examples:
            - '2024-01-15T10:30:00Z'
          description: ISO 8601 timestamp of when the transaction was initiated
        createdAt:
          type: string
          examples:
            - '2024-01-15T10:30:00Z'
          description: ISO 8601 timestamp of creation
        updatedAt:
          type: string
          examples:
            - '2024-01-15T10:35:00Z'
          description: ISO 8601 timestamp of last update
        status:
          type: string
          const: VOID
        originalAmount:
          $ref: '#/components/schemas/AmountBreakdown'
          description: Amount in the original transaction currency
        amount:
          $ref: '#/components/schemas/AmountBreakdown'
          description: Amount charged to the cardholder
      required:
        - id
        - accountId
        - cardId
        - channel
        - digitalWallet
        - originalCurrency
        - currency
        - merchant
        - fees
        - events
        - occurredAt
        - createdAt
        - updatedAt
        - status
        - originalAmount
        - amount
      description: Fully reversed authorization or zero-amount verification
    CardTransactionMerchant:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: >-
            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.
        cardAcceptorId:
          anyOf:
            - type: string
            - type: 'null'
          examples:
            - '000123456789012'
          description: >-
            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.
        name:
          type: string
          description: Merchant name
        city:
          anyOf:
            - type: string
            - type: 'null'
          description: Merchant city
        postCode:
          anyOf:
            - type: string
            - type: 'null'
          description: Merchant postal or ZIP code
        state:
          anyOf:
            - type: string
            - type: 'null'
          description: Merchant state or province
        country:
          type: string
          minLength: 2
          maxLength: 2
          examples:
            - US
            - GB
            - DE
          description: ISO 3166-1 alpha-2 country code
        mccCode:
          type: string
          examples:
            - '5411'
            - '5812'
          description: Merchant Category Code
        mccCategory:
          type: string
          examples:
            - Grocery Stores
            - Eating Places & Restaurants
          description: MCC category description
      required:
        - id
        - cardAcceptorId
        - name
        - city
        - postCode
        - state
        - mccCode
        - mccCategory
      description: Merchant details
    CardTransactionFees:
      type: object
      properties:
        atm:
          type: number
          minimum: 0
          examples:
            - 100.5
            - 0
            - 1234.99
          description: ATM withdrawal markup charged to the cardholder (card currency)
        fx:
          type: number
          minimum: 0
          examples:
            - 100.5
            - 0
            - 1234.99
          description: FX markup charged to the cardholder (card currency)
      required:
        - atm
        - fx
      description: >-
        Cardholder fee breakdown in the card billing currency. Always present;
        zeros when no fee applied.
    TransactionEvent:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Event identifier
        type:
          type: string
          enum:
            - AUTHORIZATION
            - CLEARING
            - REVERSAL
            - REFUND
            - DECLINE
            - DISPUTE_REFUND
          description: >-
            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.
          example: AUTHORIZATION
        originalAmount:
          type: number
          minimum: 0
          examples:
            - 100.5
            - 0
            - 1234.99
          description: Event amount in the event-level original currency
        originalCurrency:
          type: string
          examples:
            - USD
            - HKD
            - EUR
          description: >-
            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.
        amount:
          type: number
          minimum: 0
          examples:
            - 100.5
            - 0
            - 1234.99
          description: Event amount charged to the cardholder (card currency)
        fees:
          $ref: '#/components/schemas/CardTransactionFees'
          description: Cardholder fees charged on this event (card currency)
        occurredAt:
          type: string
          examples:
            - '2024-01-15T10:30:00Z'
          description: ISO 8601 timestamp of when the event occurred
        createdAt:
          type: string
          examples:
            - '2024-01-15T10:30:05Z'
          description: ISO 8601 timestamp of when the event was recorded
      required:
        - id
        - type
        - originalAmount
        - originalCurrency
        - amount
        - fees
        - occurredAt
        - createdAt
      description: A single lifecycle event on the transaction
    AmountBreakdown:
      type: object
      properties:
        authorized:
          type: number
          minimum: 0
          examples:
            - 100.5
            - 0
            - 1234.99
          description: Original authorized amount before reversals
        reversed:
          type: number
          minimum: 0
          examples:
            - 100.5
            - 0
            - 1234.99
          description: Total amount reversed (credited back)
        current:
          type: number
          minimum: 0
          examples:
            - 100.5
            - 0
            - 1234.99
          description: Effective current amount (authorized - reversed, minimum 0)
      required:
        - authorized
        - reversed
        - current
      description: Amount breakdown showing authorized, reversed, and current values
    ClearedAmountBreakdown:
      type: object
      properties:
        cleared:
          type: number
          minimum: 0
          examples:
            - 100.5
            - 0
            - 1234.99
          description: Total settled amount
        refunded:
          type: number
          minimum: 0
          examples:
            - 100.5
            - 0
            - 1234.99
          description: >-
            Total amount refunded, by the merchant (REFUND events) or through a
            dispute (DISPUTE_REFUND events)
        current:
          type: number
          minimum: 0
          examples:
            - 100.5
            - 0
            - 1234.99
          description: Effective current amount (cleared - refunded, minimum 0)
      required:
        - cleared
        - refunded
        - current
      description: Amount breakdown showing cleared, refunded, and current values
    DeclineReason:
      type: object
      properties:
        code:
          type: string
          enum:
            - INSUFFICIENT_BALANCE
            - INSUFFICIENT_MASTER_BALANCE
            - CARD_NOT_ACTIVE
            - CARD_NOT_ACTIVATED
            - CARD_EXPIRED
            - CARD_FROZEN
            - CARD_BLOCKED
            - CARD_REPORTED_LOST
            - CARD_REPORTED_STOLEN
            - ACCOUNT_NOT_ACTIVE
            - INCORRECT_PIN
            - INCORRECT_CVV
            - INVALID_CARD_DETAILS
            - CONTACTLESS_NOT_SUPPORTED
            - TERMINAL_ERROR
            - CASH_SERVICE_NOT_AVAILABLE
            - WITHDRAWALS_NOT_ALLOWED
            - ATM_WITHDRAWAL_LIMIT_EXCEEDED
            - ATM_WITHDRAWAL_FREQUENCY_EXCEEDED
            - MERCHANT_CARD_TYPE_MISMATCH
            - MERCHANT_CATEGORY_CODE_NOT_ALLOWED
            - TRANSACTION_TYPE_NOT_ALLOWED
            - MERCHANT_NOT_ALLOWED
            - CHANNEL_NOT_ALLOWED
            - TRANSACTION_AMOUNT_LIMIT_EXCEEDED
            - SPEND_LIMIT_EXCEEDED
            - AUTHORIZATION_COUNT_LIMIT_EXCEEDED
            - TRANSACTION_NOT_ALLOWED
            - NETWORK_DECLINE
            - SUSPECTED_FRAUD
            - INTERNAL_ERROR
          description: >-
            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`.
          example: INSUFFICIENT_BALANCE
        message:
          type: string
          description: >-
            Cardholder-facing description of the decline reason. Safe to render
            directly in your UI as a sensible default.
      required:
        - code
        - message
      description: Reason the transaction was declined
    DeclinedPolicy:
      type: object
      properties:
        id:
          type: string
          description: >-
            ID of the policy that declined the transaction. A UUID for your
            policies; a stable identifier for platform policies.
        type:
          type: string
          enum:
            - MERCHANT_RESTRICTION
            - CHANNEL_RESTRICTION
            - TRANSACTION_AMOUNT_LIMIT
            - SPEND_LIMIT
            - AUTHORIZATION_COUNT_LIMIT
          example: MERCHANT_RESTRICTION
        scopeType:
          type: string
          enum:
            - PROJECT
            - USER
            - CARD
          description: The level the policy was attached to.
          example: PROJECT
        name:
          type: string
          minLength: 1
          maxLength: 128
          description: Human-readable label.
      required:
        - id
        - type
        - scopeType
        - name
      description: The policy that declined the transaction.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key as Bearer token

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.