Wise card-kiosk-collection API

openapi: 3.1.0
info:
  title: Wise Platform 3ds card-kiosk-collection 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-kiosk-collection
  x-displayName: Card Kiosk Collection
  description: 'These APIs are designed to allow you to print and encrypt your card directly from a kiosk machine. The card information will be sent to our card manufacturer to configure and print the card on-site on a kiosk machine.


    The card printing process will automatically begin once the request is received by our card manufacturer.


    During the printing process, you will be notified via webhook about any [card production status change](/guides/developer/webhooks/event-types#cards-card-production-status-change).


    Before using these APIs, make sure to read the guide on [kiosk collection](/guides/product/issue-cards/card-kiosk-collection#card-kiosk-collection).


    {% admonition type="warning" %}

    Please reach out to your Implementation Manager for more information on these APIs.

    {% /admonition %}


    **Testing**: In the sandbox environment, use the [card production simulation API](/api-reference/simulation/simulationcardproduction) to test your integration with various production statuses and error scenarios.


    Production status flow {% .title-2 .m-t-5 %}


    These statuses represent the lifecycle of a card production:


    - `READY` - Card is ready for production. The [produce card endpoint](/api-reference/card-kiosk-collection/cardkioskcollectionproduce) can be called.

    - `IN_PROGRESS` - Card is being produced at the kiosk machine (chip encryption and printing in progress).

    - `PRODUCED` - Card has been successfully produced and collected from the kiosk. This is a final state.

    - `PRODUCTION_ERROR` - Card production failed. Check the errorCode to identify the issue, resolve it, then retry using the [produce card endpoint](/api-reference/card-kiosk-collection/cardkioskcollectionproduce).


    A card with production status `PRODUCED` will trigger an asynchronous call to update the associated card order to `PRODUCED` status.


    ![Card production status flow](/images/diagrams/card-production-status-flow.png)

    '
paths:
  /v3/spend/profiles/{profileId}/cards/{cardToken}/production:
    put:
      tags:
      - card-kiosk-collection
      summary: Produce a card
      operationId: cardKioskCollectionProduce
      description: 'Sends the card production request to a kiosk machine. To confirm that card information has been successfully created, listen to the [card-production-status-change](/guides/developer/webhooks/event-types#cards-card-production-status-change) webhook with status `READY`.


        {% admonition type="warning" %}

        Cards that were created over 60 days ago will result in a 422 error code and cannot be retried. This is due to the data being obfuscated on our side. In this case, a new card order has to be created.

        {% /admonition %}

        '
      security:
      - UserToken: []
      parameters:
      - name: profileId
        in: path
        required: true
        description: The profile ID (personal or business) that owns the card.
        schema:
          type: integer
          format: int64
        example: 123456
      - name: cardToken
        in: path
        required: true
        description: The unique token identifying the card.
        schema:
          type: string
        example: ca0c8154-1e14-4464-a1ce-dcea7dc3de52
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Request body for producing a card at a kiosk machine.
              required:
              - kioskId
              properties:
                kioskId:
                  type: string
                  description: Identifier that specifies on which kiosk the card should be produced.
                  example: WIS00001
      responses:
        '200':
          description: OK - The card information has been successfully sent to the kiosk machine.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductionStatus'
              example:
                status: IN_PROGRESS
                kioskId: WIS00001
                occurredAt: '2024-01-01T12:24:56.121Z'
          headers:
            X-External-Correlation-Id:
              $ref: '#/components/headers/X-External-Correlation-Id'
            x-trace-id:
              $ref: '#/components/headers/x-trace-id'
        '422':
          description: Unprocessable Content - The card information can't be processed by the kiosk machine. For more details, check the error code returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductionStatus'
              example:
                status: REQUEST_ERROR
                kioskId: WIS00001
                occurredAt: '2024-01-01T12:24:56.121Z'
                errorCode: PIN_VERIFICATION_FAILED
                description: The PIN cannot be verified because the server is unreachable
          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:
      tags:
      - card-kiosk-collection
      summary: Retrieve card production status
      operationId: cardKioskCollectionProductionGet
      description: 'Retrieves the current production status of a card at a kiosk machine.


        **Best practice**: Subscribe to the [card production status change](/guides/developer/webhooks/event-types#cards-card-production-status-change) webhook for real-time notifications. Use this endpoint only when you need to synchronously check the status.

        '
      security:
      - UserToken: []
      parameters:
      - name: profileId
        in: path
        required: true
        description: The profile ID (personal or business) that owns the card.
        schema:
          type: integer
          format: int64
        example: 123456
      - name: cardToken
        in: path
        required: true
        description: The unique token identifying the card.
        schema:
          type: string
        example: ca0c8154-1e14-4464-a1ce-dcea7dc3de52
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      responses:
        '200':
          description: OK - Successfully retrieved card production status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductionStatus'
              example:
                status: READY
                kioskId: null
                occurredAt: '2024-01-01T12:24:56.124Z'
                errorCode: null
                description: Card ready for production
          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:
  schemas:
    ProductionStatus:
      type: object
      description: Represents the production status of a card at a kiosk machine.
      properties:
        status:
          type: string
          description: 'Current production status:

            - `READY` - Card is ready for production

            - `IN_PROGRESS` - Card is in production at the kiosk machine

            - `PRODUCED` - Card is produced and collected. This is a final state

            - `PRODUCTION_ERROR` - Card production failed

            - `REQUEST_ERROR` - Card production request failed

            '
          enum:
          - READY
          - IN_PROGRESS
          - PRODUCED
          - PRODUCTION_ERROR
          - REQUEST_ERROR
          example: IN_PROGRESS
        kioskId:
          type:
          - string
          - 'null'
          description: Identifier that specifies which kiosk machine is producing the card. When the status is `READY`, this value is null.
          example: WIS00001
        occurredAt:
          type: string
          format: date-time
          description: Time when the card production request has been sent to the kiosk machine (ISO 8601 format).
          example: '2024-01-01T12:24:56.121Z'
        errorCode:
          type:
          - string
          - 'null'
          description: 'Code returned when card production is not successful. Nullable.


            **Request errors** - Returned when `status` is `REQUEST_ERROR`:

            - `UNKNOWN_ERROR` - An error occurred on the server

            - `REQUEST_ALREADY_EXISTS` - The request has already been submitted

            - `KIOSK_ID_NOT_FOUND` - The kiosk ID does not exist

            - `CARD_TYPE_NOT_FOUND` - The card type does not exist

            - `INVALID_FIELD_VALUE` - Some field values are unexpected

            - `INVALID_PIN_FORMAT` - The PIN does not follow ISO0 or ISO2 standard

            - `EMPTY_OR_NULL_FIELD_VALUE` - Some required fields are empty or null

            - `EMPTY_OR_NULL_OR_WRONG_SIZE_FIELD_VALUE` - Some required fields are empty, null, or have incorrect lengths

            - `CHARSET_NOT_SUPPORTED` - The character set for some fields is not supported

            - `INVALID_FIELD_FORMAT` - Some field formats are invalid

            - `INVALID_FIELD_ENCODING` - The encoding for some fields is not expected

            - `CDATA_ENCODING_OR_FORMATING_ERROR` - The encoding or formatting for XML text field values is incorrect

            - `PIN_LENGTH_ERROR` - The PIN length is incorrect

            - `PIN_VERIFICATION_FAILED` - The PIN cannot be verified because the server is unreachable

            - `DATA_PREPARATION_FAILED` - The server failed to parse the request

            - `PARTIAL_DATA_RECEIVED` - Only part of the expected data has been received

            - `NO_BRANCH_LINKED_TO_KIOSK` - The kiosk has not been linked to any branch

            - `IMAGE_SERVER_ERROR` - The image server is unreachable or failed to process the data

            - `PAN_ALREADY_EXISTS` - The PAN already exists

            - `PRINTER_OR_SATELLITE_NOT_READY` - The printer or satellite is not ready to start the production

            - `REQUEST_CREATED_BUT_NOT_STARTED` - The request has been created, but production is pending until the printer or satellite is ready

            - `UNABLE_TO_ACCEPT_REQUEST` - The system is currently busy and cannot accept new requests at this time


            **Production errors** - Returned when `status` is `PRODUCTION_ERROR`:

            - `CB_NOT_AVAILABLE` - Main server error: central base not available

            - `CB_DB_NOT_AVAILABLE` - Main server error: database not available

            - `CB_NETWORK_NOT_AVAILABLE` - Main server error: network not available

            - `CB_AUTHENTICATION_FAILED` - Main server error: user authentication verification failed

            - `CB_SERVICE_NOT_ALLOWED` - Main server error: the accessed service requires a higher security level

            - `CB_TIME` - Main server error: timeout occurred on the Central Base side

            - `DP_NOT_AVAILABLE` - Data processing error: the Data preparation module is not available

            - `DP_IO_ERROR` - Data processing error: Input/Output error when communicating with the DP

            - `DP_TIMEOUT` - Data processing error: timeout error

            - `SAT_SERVER_NOT_REACHABLE` - Satellite agent error: the server is not reachable

            - `SAT_AUTHENTICATION_FAILED` - Satellite agent error: user authentication failed on satellite

            - `SAT_NETWORK_NOT_AVAILABLE` - Satellite agent error: the network is not available

            - `PRT_NOT_REACHABLE` - Printer error: printer is not reachable

            - `PRT_SETUP_ERROR` - Printer error: printer setup is incorrect

            - `PRT_TIMEOUT` - Printer error: printer timeout

            - `PRT_RIBBON` - Printer error: ribbon error

            - `PRT_LOCK_ERROR` - Printer error: printer physically unlocked

            - `PRT_RIBBON_MISSING` - Printer error: ribbon is missing

            - `PRT_RIBBON_ENDED` - Printer error: ribbon has ended

            - `PRT_COVER_OPEN` - Printer error: printer cover is open

            - `PRT_PAUSED` - Printer error: printer paused

            - `PRD_UNEXPECTED_DATA` - Production error: production data is incorrect

            - `PRD_FEEDER_EMPTY` - Production error: feeder is empty

            - `PRD_FEEDER_JAM` - Production error: feeder card jam

            - `PRD_HOPPER_FULL` - Production error: hopper is full

            - `PRD_HOPPER_DOOR` - Production error: hopper door is open

            - `PRD_HOPPER_JAM` - Production error: hopper card jam

            - `PRD_MAGSTRIPE` - Production error: error occurred during magstripe encoding

            - `PRD_SMARTCARD` - Production error: error occurred during chip personalization

            - `PRD_EMBOSSER` - Production error: error occurred during embossing

            - `PRD_TIMEOUT` - Production error: production timeout has been reached

            - `PRD_REJECT_FULL` - Production error: reject box is full

            - `PRD_SMARTCARD_CARD_NOT_IN_READER` - Production error: card is not in reader

            - `PRD_FINAL_VALIDATION_NOK` - Production error: user has rejected card production

            - `INV_NOT_INITIALIZED` - Production error: inventory not initialized

            - `UNKNOWN_ERROR` - Unknown error

            '
          example: PIN_VERIFICATION_FAILED
        description:
          type:
          - string
          - 'null'
          description: Detailed description of the error code.
          example: The PIN cannot be verified because the server is unreachable
  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
  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