openapi: 3.1.0
info:
  title: Wise Platform 3ds spend-controls 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: spend-controls
  x-displayName: Spend Controls
  description: 'Control which card transactions are permitted by creating rules based on merchant category code (MCC) or transaction currency.


    An authorisation rule dictates whether transactions should be declined or approved based on a pre-determined set of rules. A transaction can only pass if it satisfies all the applied rules.


    Creating a rule has no practical implication until it is [applied](/api-reference/spend-controls/spendcontrolsruleapply). Applying a rule results in the authorisation rule being evaluated against every incoming card authorisation request.


    Rules are scoped at the application level. Use a [client credentials token](/api-reference/oauth-token/oauthtokencreate) to call these endpoints.

    '
paths:
  /v3/spend/applications/{clientId}/spend-controls/rules:
    post:
      operationId: spendControlsRuleCreate
      summary: Add a new authorisation rule
      description: 'Creates an authorisation rule. It won''t be enabled unless it is [applied](/api-reference/spend-controls/spendcontrolsruleapply).


        {% admonition type="warning" %}

        An `ALLOW` rule permits only the transactions that match the specified criteria and blocks all others. For instance, a rule allowing `SGD` transactions will block all transactions that are not in `SGD`.

        {% /admonition %}

        '
      tags:
      - spend-controls
      security:
      - ClientCredentialsToken: []
      parameters:
      - name: clientId
        in: path
        required: true
        description: The application client ID.
        schema:
          type: string
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  enum:
                  - MCC
                  - CURRENCY
                  description: The type of authorisation rule.
                operation:
                  type: string
                  enum:
                  - ALLOW
                  - BLOCK
                  description: Determines whether the transactions should be allowed or blocked.
                description:
                  type: string
                  description: The description of the authorisation rule.
                values:
                  type: array
                  items:
                    type: string
                  description: A list of values based on the `type` of rule. For example, setting `MCC` as `type` requires `values` to be set as `["1234", "5678"]`.
            example:
              description: Blocking all transactions from MCC 1234 and 5678
              type: MCC
              operation: BLOCK
              values:
              - '1234'
              - '5678'
      responses:
        '200':
          description: The created rule.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rule'
          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'
    get:
      operationId: spendControlsRulesList
      summary: List all authorisation rules
      description: 'Retrieves all the existing authorisation rules, regardless of whether or not they are applied.

        '
      tags:
      - spend-controls
      security:
      - ClientCredentialsToken: []
      parameters:
      - name: clientId
        in: path
        required: true
        description: The application client ID.
        schema:
          type: string
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      responses:
        '200':
          description: A list of authorisation rules.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/rule'
              example:
              - id: 1
                description: Blacklist gambling MCCs
                type: MCC
                operation: BLOCK
                values:
                - '7801'
                - '7802'
                - '7995'
                - '9754'
          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'
  /v3/spend/applications/{clientId}/spend-controls/rules/apply:
    post:
      operationId: spendControlsRuleApply
      summary: Apply an authorisation rule
      description: 'Apply an authorisation rule. This will result in the rule being evaluated against every incoming card authorisation request.

        '
      tags:
      - spend-controls
      security:
      - ClientCredentialsToken: []
      parameters:
      - name: clientId
        in: path
        required: true
        description: The application client ID.
        schema:
          type: string
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ruleId:
                  type: string
                  description: The ID of the authorisation rule.
            example:
              ruleId: '123'
      responses:
        '200':
          description: Rule applied successfully.
          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'
  /v3/spend/applications/{clientId}/spend-controls/rules/unapply:
    post:
      operationId: spendControlsRuleUnapply
      summary: Unapply an authorisation rule
      description: 'Deactivates an authorisation rule. This will result in all card transactions **not** being evaluated against this rule.


        The rule still [exists](/api-reference/spend-controls/spendcontrolsruleslist) and can be [applied](/api-reference/spend-controls/spendcontrolsruleapply) again.

        '
      tags:
      - spend-controls
      security:
      - ClientCredentialsToken: []
      parameters:
      - name: clientId
        in: path
        required: true
        description: The application client ID.
        schema:
          type: string
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ruleId:
                  type: string
                  description: The ID of the authorisation rule.
            example:
              ruleId: '123'
      responses:
        '200':
          description: Rule unapplied successfully.
          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'
  /v3/spend/applications/{clientId}/spend-controls/rules/applied:
    get:
      operationId: spendControlsAppliedRulesList
      summary: List applied authorisation rules
      description: 'Returns the list of all the active authorisation rules that have been applied.

        '
      tags:
      - spend-controls
      security:
      - ClientCredentialsToken: []
      parameters:
      - name: clientId
        in: path
        required: true
        description: The application client ID.
        schema:
          type: string
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      responses:
        '200':
          description: A list of applied rule IDs.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    ruleId:
                      type: integer
                      format: int64
                      description: The ID of the applied authorisation rule.
              example:
              - ruleId: 123
              - ruleId: 456
          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'
  /v3/spend/applications/{clientId}/spend-controls/rules/{ruleId}:
    delete:
      operationId: spendControlsRuleDelete
      summary: Delete an authorisation rule
      description: 'Deletes an authorisation rule that is **currently not applied**.

        If a rule is applied, you should [unapply](/api-reference/spend-controls/spendcontrolsruleunapply) the rule before deleting it.

        '
      tags:
      - spend-controls
      security:
      - ClientCredentialsToken: []
      parameters:
      - name: clientId
        in: path
        required: true
        description: The application client ID.
        schema:
          type: string
      - name: ruleId
        in: path
        required: true
        description: The ID of the authorisation rule to delete.
        schema:
          type: integer
          format: int64
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      responses:
        '200':
          description: Rule deleted successfully.
          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'
components:
  parameters:
    X-External-Correlation-Id:
      x-global: true
      name: X-External-Correlation-Id
      in: header
      required: false
      description: 'Optional UUID for correlating requests across systems. If provided, Wise echoes it back in the response. Maximum 36 characters. [Learn more](/guides/developer/headers/correlation-id).

        '
      schema:
        type: string
        format: uuid
        maxLength: 36
      example: f47ac10b-58cc-4372-a567-0e02b2c3d479
  headers:
    X-External-Correlation-Id:
      x-global: true
      description: Echoed back when `X-External-Correlation-Id` was included in the request. [Learn more](/guides/developer/headers/correlation-id).
      schema:
        type: string
        format: uuid
        maxLength: 36
      example: f47ac10b-58cc-4372-a567-0e02b2c3d479
    x-trace-id:
      x-global: true
      description: Unique trace identifier assigned by Wise. Useful when contacting support about a specific request.
      schema:
        type: string
      example: fba501b6d453b96789f52338f019341f
  schemas:
    rule:
      title: Authorisation Rule
      x-tags:
      - spend-controls
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: The unique ID for the authorisation rule.
        type:
          type: string
          enum:
          - MCC
          - CURRENCY
          description: The type of authorisation rule.
        operation:
          type: string
          enum:
          - ALLOW
          - BLOCK
          description: Determines whether the transactions should be allowed or blocked.
        description:
          type: string
          description: The description of the authorisation rule.
        values:
          type: array
          items:
            type: string
          description: A list of values based on the `type` of rule configured.
      example:
        id: 123
        description: my authorisation rule
        type: MCC
        operation: BLOCK
        values:
        - '1234'
        - '5678'
  responses:
    '429':
      x-global: true
      description: Rate limit exceeded. Retry after the number of seconds specified in the `Retry-After` header.
      headers:
        Retry-After:
          description: Number of seconds to wait before retrying the request.
          schema:
            type: integer
          example: 5
        X-Rate-Limited-By:
          description: Identifies the rate limiter that triggered the 429 response.
          schema:
            type: string
          example: wise-public-api
        X-External-Correlation-Id:
          $ref: '#/components/headers/X-External-Correlation-Id'
        x-trace-id:
          $ref: '#/components/headers/x-trace-id'
      content:
        application/json:
          schema:
            type: object
  securitySchemes:
    UserToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'User Access Token for making API calls on behalf of a Wise user.


        Can be obtained via two OAuth 2.0 flows:

        - **registration_code grant**: For partners creating users via API

        - **authorization_code grant**: For partners using Wise''s authorization page


        Access tokens are valid for 12 hours and can be refreshed using a refresh token.

        '
    PersonalToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Personal API Token for individual personal or small business users.

        Generated from Wise.com > Settings > Connect and manage apps > API tokens.

        Has limited API access compared to OAuth tokens (PSD2 restrictions apply for EU/UK users).

        '
    ClientCredentialsToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Application-level token for partner operations that don''t require a specific user context, such as bulk settlement and card spend controls.


        Obtained via `POST /oauth/token` with Basic Authentication (client-id:client-secret) and `grant_type=client_credentials`.


        Valid for 12 hours. No refresh token — fetch a new token when expired.


        See [create an OAuth token](/api-reference/oauth-token/oauthtokencreate) for details.

        '
    BasicAuth:
      type: http
      scheme: basic
      description: 'Basic Authentication using your Client ID and Client Secret as the username and password.


        Client credentials are provided by Wise when your partnership begins. See [Getting Started](/guides/developer) for details.

        '
x-tagGroups:
- name: Authentication
  tags:
  - oauth-token
- name: Enhanced Security
  tags:
  - jose
- name: Users
  tags:
  - user
  - claim-account
- name: Profiles
  tags:
  - profile
  - activity
  - address
- name: Verification
  tags:
  - kyc-review
  - verification
  - facetec
- name: Strong Customer Authentication
  tags:
  - sca-ott
  - sca-sessions
  - sca-pin
  - sca-facemaps
  - sca-device-fingerprints
  - sca-otp
  - user-security
- name: Balances
  tags:
  - balance
  - balance-statement
  - bank-account-details
  - multi-currency-account
- name: Cards
  tags:
  - card
  - card-sensitive-details
  - 3ds
  - card-kiosk-collection
  - card-order
  - card-transaction
  - spend-limits
  - spend-controls
  - digital-wallet
  - disputes
- name: Quotes
  tags:
  - quote
  - rate
  - comparison
- name: Recipients
  tags:
  - recipient
  - contact
- name: Transfers
  tags:
  - transfer
  - delivery-estimate
  - currencies
  - batch-group
- name: Funding
  tags:
  - payin-deposit-detail
  - direct-debit-account
  - bulk-settlement
  - payins
- name: Webhooks
  tags:
  - webhook
  - webhook-event
- name: Simulations
  tags:
  - simulation
- name: Partner Support
  tags:
  - case