Wise card-sensitive-details API

openapi: 3.2.0
info:
  title: Wise Platform Card Sensitive Details 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: card-sensitive-details
  x-displayName: Sensitive Card Details
  description: 'Wise is a PCI DSS compliant provider and stores all card data securely. The scope for PCI compliance depends on your use case and will impact how you integrate. For all sensitive card details endpoints, follow the [detailed guide](/guides/product/issue-cards/sensitive-card-details).


    **Key capabilities:**

    - Access sensitive card data (PAN, CVV, PIN) via encrypted JWE payloads


    **Related operations:**

    - For card management (list, status, permissions), see the [Cards API](/api-reference/card)

    - For ordering new cards, see the [Card Orders API](/api-reference/card-order)

    - For transaction history, see the [Card Transaction API](/api-reference/card-transaction)'
paths:
  /twcard-data/v1/clientSideEncryption/fetchEncryptingKey:
    get:
      operationId: cardEncryptionKeyGet
      summary: Fetch RSA encryption key
      description: 'Fetches Wise''s RSA public key required for encrypting sensitive card data requests.


        This key is used in the [sensitive card details flow](/guides/product/issue-cards/sensitive-card-details) to create JWE (JSON Web Encryption) payloads.

        '
      tags:
      - card-sensitive-details
      servers:
      - url: https://twcard.wise.com
        description: Production Environment
      - url: https://twcard.wise-sandbox.com
        description: Sandbox Environment
      security:
      - UserToken: []
      responses:
        '200':
          description: RSA encryption key retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  version:
                    type: integer
                    format: int32
                    description: Version of the encryption key.
                    example: 1
                  key:
                    type: string
                    description: The RSA public key.
                    example: <encryption key>
          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'
  /twcard-data/v1/sensitive-card-data/details:
    post:
      operationId: cardSensitiveDetailsGet
      summary: Get sensitive card details
      description: 'Fetches the card''s Primary Account Number (PAN), security code (CVV2), expiry date, and cardholder name.


        Requires an encrypted JWE payload for security. See the [sensitive card details guide](/guides/product/issue-cards/sensitive-card-details) for implementation details.


        To retrieve sensitive card details, the card must be in either `ACTIVE` or `FROZEN` status. A 403 response will be returned for cards in any other status.


        {% admonition type="warning" %}

        This endpoint is SCA protected when applicable. If your profile is registered within the UK and/or EEA, SCA most likely applies. For more information, see [implementing SCA](/guides/developer/auth-and-security/sca-and-2fa).

        {% /admonition %}

        '
      tags:
      - card-sensitive-details
      servers:
      - url: https://twcard.wise.com
        description: Production Environment
      - url: https://twcard.wise-sandbox.com
        description: Sandbox Environment
      parameters:
      - name: x-tw-twcard-card-token
        in: header
        required: true
        description: The card token identifying which card to retrieve details for.
        schema:
          type: string
          format: uuid
        example: ca0c8154-1e14-4464-a1ce-dcea7dc3de52
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      security:
      - UserToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - keyVersion
              - encryptedPayload
              properties:
                keyVersion:
                  type: integer
                  format: int32
                  description: The version of the encryption key to use. Always set to 1.
                  example: 1
                encryptedPayload:
                  type: string
                  description: Your JWE encrypted payload.
                  example: <your JWE>
      responses:
        '200':
          description: Sensitive card details retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  nonce:
                    type: string
                    format: uuid
                    description: An arbitrary UUID issued from the cryptographic communication.
                    example: 33d51227-9ad6-4624-b4b7-7853b56076dd
                  cvv2:
                    type: string
                    description: The card CVV2 security code.
                    example: '111'
                  pan:
                    type: string
                    description: The card Primary Account Number.
                    example: '4396910000012345'
                  expiryDate:
                    type: string
                    description: The card expiry date in MM/YY format.
                    example: 10/31
                  cardholderName:
                    type: string
                    description: Name on the card.
                    example: John Smith
          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'
  /twcard-data/v1/sensitive-card-data/pin:
    post:
      operationId: cardPinGet
      summary: Get card PIN
      description: 'Fetches the card''s PIN.


        Requires an encrypted JWE payload for security. See the [sensitive card details guide](/guides/product/issue-cards/sensitive-card-details) for implementation details.


        {% admonition type="warning" %}

        This endpoint is SCA protected when applicable. If your profile is registered within the UK and/or EEA, SCA most likely applies. For more information, see [implementing SCA](/guides/developer/auth-and-security/sca-and-2fa).

        {% /admonition %}

        '
      tags:
      - card-sensitive-details
      servers:
      - url: https://twcard.wise.com
        description: Production Environment
      - url: https://twcard.wise-sandbox.com
        description: Sandbox Environment
      parameters:
      - name: x-tw-twcard-card-token
        in: header
        required: true
        description: The card token identifying which card to retrieve the PIN for.
        schema:
          type: string
          format: uuid
        example: ca0c8154-1e14-4464-a1ce-dcea7dc3de52
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      security:
      - UserToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - keyVersion
              - encryptedPayload
              properties:
                keyVersion:
                  type: integer
                  format: int32
                  description: The version of the encryption key to use. Always set to 1.
                  example: 1
                encryptedPayload:
                  type: string
                  description: Your JWE encrypted payload.
                  example: <your JWE>
      responses:
        '200':
          description: Card PIN retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  nonce:
                    type: string
                    format: uuid
                    description: An arbitrary UUID issued from the cryptographic communication.
                    example: 33d51227-9ad6-4624-b4b7-7853b56076dd
                  pin:
                    type: string
                    description: The card PIN.
                    example: '1234'
          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:
  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
  headers:
    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
    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
  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
  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