Wise simulation API

openapi: 3.1.0
info:
  title: Wise Platform 3ds simulation API
  version: ''
  description: "The Wise Platform API is a REST-based interface that enables programmatic access to Wise's payment infrastructure. All endpoints return JSON-formatted responses and use standard HTTP methods and status codes.\n{% admonition type=\"success\" name=\"New to wise?\" %}\n  We strongly recommend first reading our **[Getting Started Guide](/guides/developer/index.md)** to help you set up credentials and make your first call.\n{% /admonition %}\n\nBefore you begin {% .title-2 .m-t-5 %}\n\nTo use this API reference effectively, you should have:\n\n- Received Valid [API credentials from Wise](/guides/developer/auth-and-security/index.md) (Client ID and Client Secret)\n- Understand OAuth 2.0 authentication\n- Be familiar with RESTful API concepts\n\nCore API resources {% .title-2 .m-t-5 .m-b-0 %}\n\n| Resource | Purpose |\n|----------|---------|\n| **[Quote](/api-reference/quote)** | Exchange rate and fee calculations |\n| **[Recipient](/api-reference/recipient)** | Beneficiary account management |\n| **[Transfer](/api-reference/transfer)** | Payment creation and execution |\n| **[Balance](/api-reference/balance)** | Multi-currency account operations |\n| **[Profile](/api-reference/profile)** | Account ownership details |\n| **[Rate](/api-reference/rate)** | Current and historical exchange rates |\n\n**Not sure which workflow to build?**<br>\nStart with our [Integration Guides](/guides/product/send-money/use-cases/index.md) for step-by-step implementation examples.{% .m-t-3 .m-b-5 %}\n"
servers:
- url: https://api.wise.com
  description: Production Environment
- url: https://api.wise-sandbox.com
  description: Sandbox Environment
tags:
- name: simulation
  x-displayName: Simulations
  description: 'Use these endpoints to simulate key actions in the sandbox environment, including transfer state changes, balance top-ups, card transactions, KYC reviews, and incoming payments.


    {% admonition type="info" %}

    These features are limited to sandbox only.

    {% /admonition %}

    '
paths:
  /v1/simulation/transfers/{transferId}/{status}:
    get:
      operationId: simulationTransferStateChange
      summary: Simulate transfer state change
      description: 'Changes the transfer status to the specified state. The available state transitions are:


        - `processing` — from `incoming_payment_waiting`

        - `funds_converted` — from `processing`. Refer to regional guides for special regional requirements.

        - `outgoing_payment_sent` — from `funds_converted`

        - `bounced_back` — from `outgoing_payment_sent`

        - `funds_refunded` — from `bounced_back`. Will not trigger a refund webhook.


        {% admonition type="warning" %}

        Simulation does not work with email transfers.

        {% /admonition %}


        {% admonition type="warning" %}

        You need to fund the transfer before calling simulation endpoints. Calling the `processing` endpoint is required even after the funding call has changed the transfer state to processing automatically.

        {% /admonition %}


        {% admonition type="info" %}

        While transfer state simulation calls will respond with 200 in real time, the process internally is asynchronous. Please ensure you give at least 5 seconds in between simulation calls.

        {% /admonition %}

        '
      tags:
      - simulation
      security:
      - UserToken: []
      parameters:
      - name: transferId
        in: path
        required: true
        description: The ID of the transfer to simulate.
        schema:
          type: integer
          format: int64
      - name: status
        in: path
        required: true
        description: The target transfer status.
        schema:
          type: string
          enum:
          - processing
          - funds_converted
          - outgoing_payment_sent
          - bounced_back
          - funds_refunded
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      responses:
        '200':
          description: Transfer with updated status.
          content:
            application/json:
              example:
                id: 15574445
                user: 294205
                targetAccount: 7993919
                sourceAccount: null
                quote: 113379
                status: processing
                reference: good times
                rate: 1.2151
                created: '2017-03-14 15:25:51'
                business: null
                transferRequest: null
                details:
                  reference: good times
                hasActiveIssues: false
                sourceValue: 1000
                sourceCurrency: EUR
                targetValue: 895.32
                targetCurrency: GBP
          headers:
            X-External-Correlation-Id:
              $ref: '#/components/headers/X-External-Correlation-Id'
            x-trace-id:
              $ref: '#/components/headers/x-trace-id'
        '429':
          $ref: '#/components/responses/429'
  /v1/simulation/profiles/{profileId}/verifications:
    post:
      operationId: simulationVerification
      summary: Simulate verification for a profile
      description: 'Changes a specific profile''s verification state to `PASSED`.


        This is useful for testing the `profiles#verification-state-change` webhook and is a prerequisite for setting up a Multi-Currency Account (MCA).


        Accepts both user and application API tokens.

        '
      tags:
      - simulation
      security:
      - UserToken: []
      parameters:
      - name: profileId
        in: path
        required: true
        description: The ID of the profile to verify.
        schema:
          type: integer
          format: int64
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      responses:
        '200':
          description: Verification state changed successfully. No content returned.
          headers:
            X-External-Correlation-Id:
              $ref: '#/components/headers/X-External-Correlation-Id'
            x-trace-id:
              $ref: '#/components/headers/x-trace-id'
        '429':
          $ref: '#/components/responses/429'
  /v1/simulation/verify-profile:
    post:
      operationId: simulationVerifyProfile
      summary: Simulate verification for all profiles
      description: 'Verifies all profiles associated with the authenticated user, changing their verification state to `PASSED`.


        This is useful for testing the `profiles#verification-state-change` webhook and is a prerequisite for setting up a Multi-Currency Account (MCA).


        Accepts user API tokens only. The profiles are identified via the token.

        '
      tags:
      - simulation
      security:
      - UserToken: []
      responses:
        '200':
          description: Verification state changed successfully. No content returned.
          headers:
            X-External-Correlation-Id:
              $ref: '#/components/headers/X-External-Correlation-Id'
            x-trace-id:
              $ref: '#/components/headers/x-trace-id'
        '429':
          $ref: '#/components/responses/429'
      parameters:
      - $ref: '#/components/parameters/X-External-Correlation-Id'
  /v1/simulation/balance/topup:
    post:
      operationId: simulationBalanceTopup
      summary: Simulate a balance top-up
      description: 'Simulates a top-up so that a balance can be used to fund transfers and/or card spend.

        '
      tags:
      - simulation
      security:
      - UserToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - profileId
              - balanceId
              - currency
              - amount
              properties:
                profileId:
                  type: integer
                  format: int64
                  description: The profile ID linked to the balance account.
                balanceId:
                  type: integer
                  format: int64
                  description: The ID of the balance account that is going to receive the funds.
                currency:
                  type: string
                  description: The currency to top up the balance account in. Must be the same currency as the balance account.
                amount:
                  type: number
                  description: The amount to top up the balance account with.
                channel:
                  type: string
                  enum:
                  - TRANSFER
                  - CARD
                  description: Type of top-up. Not providing a channel will default to `CARD`.
            example:
              profileId: 2
              balanceId: 5
              currency: EUR
              amount: 100
              channel: TRANSFER
      responses:
        '200':
          description: Simulated balance top-up result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  transactionId:
                    type: integer
                    format: int64
                    description: The ID of the top-up transaction.
                  state:
                    type: string
                    description: The state of the transaction. `COMPLETED` is always returned when using this endpoint.
                  balancesAfter:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          format: int64
                          description: The ID of the balance account.
                        value:
                          type: number
                          description: The new amount available in the balance account.
                        currency:
                          type: string
                          description: The currency of the balance account.
              example:
                transactionId: 5
                state: COMPLETED
                balancesAfter:
                - id: 5
                  value: 100
                  currency: EUR
          headers:
            X-External-Correlation-Id:
              $ref: '#/components/headers/X-External-Correlation-Id'
            x-trace-id:
              $ref: '#/components/headers/x-trace-id'
        '429':
          $ref: '#/components/responses/429'
      parameters:
      - $ref: '#/components/parameters/X-External-Correlation-Id'
  /v2/simulation/spend/profiles/{profileId}/cards/{cardToken}/transactions/authorisation:
    post:
      operationId: simulationCardTransactionAuthorisation
      summary: Simulate a card transaction authorisation
      description: 'Simulates a card transaction authorisation request in the sandbox environment. It can simulate ATM withdrawals, POS purchases, e-commerce transactions, and refunds. This is an authorisation hold, where funds are held, but not yet captured by the acquirer.


        The `cardNumber` represents the 16-digit Primary Account Number (PAN) of the card, and must be a valid PAN retrieved from sensitive card details. Please follow the [detailed guide](/guides/product/issue-cards/sensitive-card-details) on retrieving sensitive card details.


        #### Refund


        A refund is a 2-step process: first authorise with `transactionType` set to `REFUND`, then clear using the [clearing endpoint](/api-reference/simulation/simulationcardtransactionclearing) with the same transaction type.


        {% admonition type="warning" %}

        Refund simulation doesn''t work with Mastercard.

        {% /admonition %}

        '
      tags:
      - simulation
      security:
      - UserToken: []
      parameters:
      - name: profileId
        in: path
        required: true
        description: The profile ID.
        schema:
          type: integer
          format: int64
      - name: cardToken
        in: path
        required: true
        description: The card token.
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                pos:
                  type: string
                  description: 'The point-of-sale used for the transaction.

                    - For POS transactions: `CHIP_AND_PIN`

                    - For e-commerce transactions: `E_COMMERCE_NO_3DS`

                    - For ATM transactions: `CHIP_AND_PIN`

                    - For refund transactions: `CHIP_AND_PIN` or `E_COMMERCE_NO_3DS`

                    '
                transactionType:
                  type: string
                  description: 'The type of the transaction.

                    - For POS and e-commerce transactions: `GOODS_AND_SERVICES`

                    - For ATM transactions: `CASH_WITHDRAWAL`

                    - For refund transactions: `REFUND`

                    '
                amount:
                  type: object
                  properties:
                    value:
                      type: number
                      description: Transaction amount.
                    currency:
                      type: string
                      description: Currency code.
                mcc:
                  type: integer
                  format: int32
                  description: Merchant category code.
                cardNumber:
                  type: string
                  description: Primary Account Number of the card.
            examples:
              POS purchase:
                summary: POS purchase
                value:
                  pos: CHIP_AND_PIN
                  transactionType: GOODS_AND_SERVICES
                  amount:
                    value: 10
                    currency: SGD
                  mcc: 5499
                  cardNumber: '4242424242424242'
              E-commerce purchase:
                summary: E-commerce purchase
                value:
                  pos: E_COMMERCE_NO_3DS
                  transactionType: GOODS_AND_SERVICES
                  amount:
                    value: 10
                    currency: SGD
                  mcc: 5499
                  cardNumber: '4242424242424242'
              ATM withdrawal:
                summary: ATM withdrawal
                value:
                  pos: CHIP_AND_PIN
                  transactionType: CASH_WITHDRAWAL
                  amount:
                    value: 10
                    currency: SGD
                  mcc: 6011
                  cardNumber: '4242424242424242'
              Refund:
                summary: Refund
                value:
                  pos: CHIP_AND_PIN
                  transactionType: REFUND
                  amount:
                    value: 10
                    currency: SGD
                  mcc: 5499
                  cardNumber: '4242424242424242'
      responses:
        '200':
          description: Simulated card authorisation.
          content:
            application/json:
              schema:
                type: object
                properties:
                  reference:
                    type: object
                    description: The transaction reference. This can be used in a following request for reversal and clearing.
                  error:
                    type:
                    - string
                    - 'null'
                    description: An error returned by the transaction, if it exists.
              example:
                reference:
                  transaction:
                    acquirer:
                      institutionId: '430010'
                      name: ACQUIRER NAME
                      city: CITY NAME
                      merchantCategoryCode: 5499
                      country: GB
                      acceptorTerminalId: TERMID01
                      acceptorIdCode: CARD ACCEPTOR
                      forwardingInstitutionId: '400050'
                    card:
                      token: 59123122-223d-45f9-b840-0ad4a4f80937
                      schemeName: VISA
                      pan: '4242424242424242'
                      pin: '1234'
                      cvv1: '123'
                      icvv: '456'
                      cvv2: '789'
                      expiration:
                      - 2029
                      - 7
                      sequenceNumber: 1
                      profileId: 2
                      userId: 5
                      cardStatus: ACTIVE
                      country: SG
                      currencies:
                      - SGD
                    pos:
                      type: CHIP_AND_PIN
                      acceptsOnlinePins: true
                      maxPinLength: 12
                      supports3ds: false
                      hasChip: true
                    transactionStartTime: 1667541087.0476434
                    stan: '363054'
                    schemeTransactionId: '932290252416153'
                    retrievalReferenceNum: '230805363054'
                  requestMti: '0200'
                  authorizationIdResponse: '123646'
                error: null
          headers:
            X-External-Correlation-Id:
              $ref: '#/components/headers/X-External-Correlation-Id'
            x-trace-id:
              $ref: '#/components/headers/x-trace-id'
        '429':
          $ref: '#/components/responses/429'
  /v1/simulation/spend/profiles/{profileId}/cards/{cardToken}/transactions/clearing:
    post:
      operationId: simulationCardTransactionClearing
      summary: Simulate a card transaction clearing
      description: 'Simulates a transaction clearing request in the sandbox environment. This is done after the authorisation. The `ref` field can be copied from the `reference` object in the authorisation response.


        To clear a previous authorisation, the `ref` details must match the previous authorisation request. The `amount` does not have to match the previous authorisation request, it can be more or less than the authorisation request amount.


        {% admonition type="warning" %}

        Clearing simulation doesn''t work with Mastercard.

        {% /admonition %}


        #### Refund


        A refund is a 2-step process: first [authorise](/api-reference/simulation/simulationcardtransactionauthorisation) with `transactionType` set to `REFUND`, then clear using this endpoint with the same transaction type.

        '
      tags:
      - simulation
      security:
      - UserToken: []
      parameters:
      - name: profileId
        in: path
        required: true
        description: The profile ID.
        schema:
          type: integer
          format: int64
      - name: cardToken
        in: path
        required: true
        description: The card token.
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: object
                  properties:
                    value:
                      type: number
                      description: Transaction amount.
                    currency:
                      type: string
                      description: Currency code.
                transactionType:
                  type: string
                  description: The type of the transaction. Use the same transaction type from the previous authorisation request.
                ref:
                  type: object
                  description: The transaction reference. This can be obtained from a previous authorisation request.
            example:
              amount:
                value: 10
                currency: SGD
              transactionType: GOODS_AND_SERVICES
              ref:
                transaction:
                  acquirer:
                    institutionId: '430010'
                    name: ACQUIRER NAME
                    city: CITY NAME
                    merchantCategoryCode: 5499
                    country: GB
                    acceptorTerminalId: TERMID01
                    acceptorIdCode: CARD ACCEPTOR
                    forwardingInstitutionId: '400050'
                  card:
                    token: 59123122-223d-45f9-b840-0ad4a4f80937
                    schemeName: VISA
                    pan: '4242424242424242'
                    pin: '1234'
                    cvv1: '123'
                    icvv: '456'
                    cvv2: '789'
                    expiration:
                    - 2029
                    - 7
                    sequenceNumber: 1
                    profileId: 2
                    userId: 5
                    cardStatus: ACTIVE
                    country: SG
                    currencies:
                    - SGD
                  pos:
                    type: CHIP_AND_PIN
                    acceptsOnlinePins: true
                    maxPinLength: 12
                    supports3ds: false
                    hasChip: true
                  transactionStartTime: 1667541087.0476434
                  stan: '363054'
                  schemeTransactionId: '932290252416153'
                  retrievalReferenceNum: '230805363054'
                requestMti: '0200'
                authorizationIdResponse: '123646'
      responses:
        '200':
          description: Simulated transaction clearing result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  reference:
                    type: object
                    description: The transaction reference.
                  error:
                    type:
                    - string
                    - 'null'
                    description: An error returned by the transaction, if it exists.
              example:
                reference:
                  transaction:
                    acquirer:
                      institutionId: '430010'
                      name: ACQUIRER NAME
                      city: CITY NAME
                      merchantCategoryCode: 5499
                      country: GB
                      acceptorTerminalId: TERMID01
                      acceptorIdCode: CARD ACCEPTOR
                      forwardingInstitutionId: '400050'
                    card:
                      token: 59123122-223d-45f9-b840-0ad4a4f80937
                      schemeName: VISA
                      pan: '4242424242424242'
                      pin: '1234'
                      cvv1: '123'
                      icvv: '456'
                      cvv2: '789'
                      expiration:
                      - 2029
                      - 7
                      sequenceNumber: 1
                      profileId: 2
                      userId: 5
                      cardStatus: ACTIVE
                      country: SG
                      currencies:
                      - SGD
                    pos:
                      type: CHIP_AND_PIN
                      acceptsOnlinePins: true
                      maxPinLength: 12
                      supports3ds: false
                      hasChip: true
                    transactionStartTime: 1667541087.0476434
                    stan: '363054'
                    schemeTransactionId: '932290252416153'
                    retrievalReferenceNum: '230805363054'
                  requestMti: '0200'
                  authorizationIdResponse: '123646'
                error: null
          headers:
            X-External-Correlation-Id:
              $ref: '#/components/headers/X-External-Correlation-Id'
            x-trace-id:
              $ref: '#/components/headers/x-trace-id'
        '429':
          $ref: '#/components/responses/429'
  /v1/simulation/spend/profiles/{profileId}/cards/{cardToken}/transactions/reversal:
    post:
      operationId: simulationCardTransactionReversal
      summary: Simulate a card transaction reversal
      description: 'Simulates a transaction reversal request in the sandbox environment. The `amount.value` field can be set to 0 for a full reversal, or a positive value that represents the intended final value of the transaction after a partial reversal.


        For example, if a transaction value was originally 10 SGD, and the intended final value is 3 SGD, `amount.value` should be set to 3. This means there is a partial refund of 7 SGD.

        '
      tags:
      - simulation
      security:
      - UserToken: []
      parameters:
      - name: profileId
        in: path
        required: true
        description: The profile ID.
        schema:
          type: integer
          format: int64
      - name: cardToken
        in: path
        required: true
        description: The card token.
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: object
                  properties:
                    value:
                      type: number
                      description: Transaction amount. Set to 0 for full reversal, or the intended final value for partial reversal.
                    currency:
                      type: string
                      description: Currency code.
                transactionType:
                  type: string
                  description: The type of the transaction. Use the same transaction type from the previous authorisation request.
                ref:
                  type: object
                  description: The transaction reference. This can be obtained from a previous authorisation request.
            example:
              amount:
                value: 3
                currency: SGD
              transactionType: GOODS_AND_SERVICES
              ref:
                transaction:
                  acquirer:
                    institutionId: '430010'
                    name: ACQUIRER NAME
                    city: CITY NAME
                    merchantCategoryCode: 5499
                    country: GB
                    acceptorTerminalId: TERMID01
                    acceptorIdCode: CARD ACCEPTOR
                    forwardingInstitutionId: '400050'
                  card:
                    token: 59123122-223d-45f9-b840-0ad4a4f80937
                    schemeName: VISA
                    pan: '4242424242424242'
                    pin: '1234'
                    cvv1: '123'
                    icvv: '456'
                    cvv2: '789'
                    expiration:
                    - 2029
                    - 7
                    sequenceNumber: 1
                    profileId: 2
                    userId: 5
                    cardStatus: ACTIVE
                    country: SG
                    currencies:
                    - SGD
                  pos:
                    type: CHIP_AND_PIN
                    acceptsOnlinePins: true
                    maxPinLength: 12
                    supports3ds: false
                    hasChip: true
                  transactionStartTime: 1667541087.0476434
                  stan: '363054'
                  schemeTransactionId: '932290252416153'
                  retrievalReferenceNum: '230805363054'
                requestMti: '0200'
                authorizationIdResponse: '123646'
      responses:
        '200':
          description: Simulated transaction reversal result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  reference:
                    type: object
                    description: The transaction reference.
                  error:
                    type:
                    - string
                    - 'null'
                    description: An error returned by the transaction, if it exists.
              example:
                reference:
                  transaction:
                    acquirer:
                      institutionId: '430010'
                      name: ACQUIRER NAME
                      city: CITY NAME
                      merchantCategoryCode: 5499
                      country: GB
                      acceptorTerminalId: TERMID01
                      acceptorIdCode: CARD ACCEPTOR
                      forwardingInstitutionId: '400050'
                    card:
                      token: 59123122-223d-45f9-b840-0ad4a4f80937
                      schemeName: VISA
                      pan: '4242424242424242'
                      pin: '1234'
                      cvv1: '123'
                      icvv: '456'
                      cvv2: '789'
                      expiration:
                      - 2029
                      - 7
                      sequenceNumber: 1
                      profileId: 2
                      userId: 5
                      cardStatus: ACTIVE
                      country: SG
                      currencies:
                      - SGD
                    pos:
                      type: CHIP_AND_PIN
                      acceptsOnlinePins: true
                      maxPinLength: 12
                      supports3ds: false
                      hasChip: true
                    transactionStartTime: 1667541087.0476434
                    stan: '363054'
                    schemeTransactionId: '932290252416153'
                    retrievalReferenceNum: '230805363054'
                  requestMti: '0200'
                  authorizationIdResponse: '123646'
                error: null
          headers:
            X-External-Correlation-Id:
              $ref: '#/components/headers/X-External-Correlation-Id'
            x-trace-id:
              $ref: '#/components/headers/x-trace-id'
        '429':
          $ref: '#/components/responses/429'
  /v2/simulation/spend/profiles/{profileId}/cards/{cardToken}/transactions:
    get:
      operationId: simulationCardTransactions
      summary: List simulated card transactions
      description: 'Returns a list of simulated card transactions, in descending order of creation time.


        To retrieve more details of a transaction, use the [get card transaction by ID](/api-reference/card-transaction/cardtransactionget) endpoint.

        '
      tags:
      - simulation
      security:
      - UserToken: []
      parameters:
      - name: profileId
        in: path
        required: true
        description: The profile ID.
        schema:
          type: integer
          format: int64
      - name: cardToken
        in: path
        required: true
        description: The card token.
        schema:
          type: string
          format: uuid
      - name: limit
        in: query
        required: false
        description: The maximum number of transactions to return. The default value is 10.
        schema:
          type: integer
          format: int32
          default: 10
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      responses:
        '200':
          description: List of simulated card transactions.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    transactionId:
                      type: integer
                      format: int64
                      description: ID of the transaction.
                    creationTime:
                      type: number
                      description: Time when the card transaction was created.
              example:
              - transactionId: 5028
                creationTime: 1723600773.748887
              - transactionId: 5027
                creationTime: 1723600659.095692
              - transactionId: 5026
                creationTime: 1723600648.133955
              - transactionId: 5025
                creationTime: 172

# --- truncated at 32 KB (58 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/wise/refs/heads/main/openapi/wise-simulation-api-openapi.yml