Klarna

Klarna Merchant Card API

The Merchant Card API from Klarna — 6 operation(s) for merchant card.

GitHub OpenAPI
Business capability
Card Transaction Processing Management BC-1340.70

Operations 7

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

POST /merchantcard/v3/promises Create a virtual card promise for an order · Klarna Create a card promise #
Ask an LLM
“How do I request virtual credit cards to pay a supplier for an order?”
“What happens to the previous card promise when I create a new one for the same order?”
Tell an agent
Create a card promise for order {order_id} with cards {cards}.
Promise virtual cards {cards} for order {order_id}.
GET /merchantcard/v3/promises/{promise_id} Get a virtual card promise · Klarna Get details of a card promise #
Ask an LLM
“Can I look up which cards were promised in a card promise?”
“Where do I check the details of an existing virtual card promise?”
Tell an agent
Get card promise {promise_id}.
Show the details of virtual card promise {promise_id}.
POST /merchantcard/v3/settlements Settle virtual cards for a completed order · Klarna Create a card settlement #
Ask an LLM
“How do I get the actual virtual card numbers once an order is complete?”
“Can I settle cards for an order without passing a promise id?”
Tell an agent
Create a card settlement for order {order_id} with key {key_id}.
Settle promise {promise_id} for completed order {order_id} using key {key_id}.
GET /merchantcard/v3/settlements/{settlement_id} Get a virtual card settlement by id · Klarna Get details of card settlement #
Ask an LLM
“Can I retrieve an existing card settlement using its settlement id?”
“Why does reading a settlement require a key id header?”
Tell an agent
Get card settlement {settlement_id} with key {KeyId}.
Retrieve the virtual cards in settlement {settlement_id} using key {KeyId}.
GET /merchantcard/v3/settlements/order/{order_id} Get the card settlement for an order · Klarna Get card settlement details for an order #
Ask an LLM
“If I only have the order id, can I find its virtual card settlement?”
“Where do I look up the settled cards belonging to a particular order?”
Tell an agent
Get the card settlement for order {order_id} with key {KeyId}.
Find the virtual card settlement of order {order_id} using key {KeyId}.
POST /merchantcard/v3/orders/{order_id}/cancel-request Request cancellation of a virtual card order · Klarna Request order cancellation #
Ask an LLM
“How do I cancel an order that has a virtual card settlement?”
“Does cancelling a virtual card order happen immediately or asynchronously?”
Tell an agent destructive · confirm first
Request cancellation of virtual card order {order_id}.
Queue card order {order_id} for cancellation.
GET /merchantcard/v3/orders/{order_id}/cancel-request Check a virtual card order cancellation · Klarna Get order cancellation status #
Ask an LLM
“Has my cancellation request for a virtual card order gone through yet?”
“Can I see whether a queued card order cancellation is still pending?”
Tell an agent
Get the cancellation status of card order {order_id}.
Check whether the cancel request for virtual card order {order_id} is done.

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/klarna/refs/heads/main/openapi/klarna-merchant-card-api-openapi.yml

Schemas & Data

📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/klarna/refs/heads/main/json-schema/klarna-cancel-order-request-status-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/klarna/refs/heads/main/json-schema/klarna-settlement-response-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/klarna/refs/heads/main/json-schema/klarna-promise-response-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/klarna/refs/heads/main/json-schema/klarna-settlement-request-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/klarna/refs/heads/main/json-schema/klarna-cancel-order-request-status-pending-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/klarna/refs/heads/main/json-schema/klarna-promise-request-schema.json

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/klarna:klarna-merchant-card-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

klarna-merchant-card-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Klarna Merchant Card Service Merchantcard API
  description: 'The Merchant Card Service (MCS) API is used to settle orders with virtual credit cards.


    Read more on Merchant card service.'
  version: 1.0.0
servers:
- url: https://api.klarna.com
tags:
- name: Merchant Card
paths:
  /merchantcard/v3/promises:
    post:
      summary: Klarna Create a card promise
      description: To create promise provide a purchase currency and the cards to be created. The old promise is automatically invalidated if a new promise is created for an order
      operationId: createPromise
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/promise_request'
      responses:
        '201':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/promise_created_response'
        '400':
          description: Bad Request
        '503':
          description: Service unavailable
      tags:
      - Merchant Card
  /merchantcard/v3/promises/{promise_id}:
    get:
      summary: Klarna Get details of a card promise
      description: To get the promise resource simply provide a promise identifier.
      operationId: readPromise
      parameters:
      - name: promise_id
        in: path
        required: true
        example: ee4a8e3a-9dfd-49e0-9ac8-ea2b6c76408c
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/promise_response'
        '403':
          description: Forbidden
        '404':
          description: Not found
      tags:
      - Merchant Card
  /merchantcard/v3/settlements:
    post:
      summary: Klarna Create a card settlement
      description: To create a settlement resource provide a completed order identifier and (optionally) a promise identifier.
      operationId: settlePromise
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/settlement_request'
      responses:
        '201':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/settlement_response'
        '400':
          description: Bad Request
        '403':
          description: Forbidden
        '503':
          description: Service unavailable
      tags:
      - Merchant Card
  /merchantcard/v3/settlements/{settlement_id}:
    get:
      summary: Klarna Get details of card settlement
      description: To get the settlement resource provide the settlement identifier.
      operationId: readSettlement
      parameters:
      - name: settlement_id
        in: path
        description: Unique settlement identifier.
        required: true
        example: b0ec0bbd-534c-4b1c-b28a-628bf33c3324
        schema:
          type: string
      - name: KeyId
        in: header
        description: Unique identifier for the public key used for encryption of the card data.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/settlement_response'
        '403':
          description: Forbidden
        '404':
          description: Not Found
      tags:
      - Merchant Card
  /merchantcard/v3/settlements/order/{order_id}:
    get:
      summary: Klarna Get card settlement details for an order
      description: To get the order's settlement resource provide the order identifier.
      operationId: readSettlementByOrderId
      parameters:
      - name: order_id
        in: path
        description: Unique identifier for the order associated to the settlement.
        required: true
        example: f3392f8b-6116-4073-ab96-e330819e2c07
        schema:
          type: string
      - name: KeyId
        in: header
        description: Unique identifier for the public key used for encryption of the card data.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/settlement_response'
        '403':
          description: Forbidden
        '404':
          description: Not Found
      tags:
      - Merchant Card
  /merchantcard/v3/orders/{order_id}/cancel-request:
    post:
      summary: Klarna Request order cancellation
      description: 'Request cancellation for an order. If the order is already cancelled, a `200` status is returned.


        Otherwise, the order will be queued for cancellation with a `202` status. Actual order cancellation will happen asynchronously at a later time. You can call the corresponding GET endpoint to view the status of the request.


        This cancellation endpoint is limited to the scope of the Virtual Credit Cards product. Therefore the order provided must have an associated Virtual Card Settlement, otherwise the call will fail.'
      operationId: postcancelorder
      parameters:
      - name: order_id
        in: path
        description: Order id you wish to cancel. This order must have an associated Virtual Credit Card Settlement.
        required: true
        example: f3392f8b-6116-4073-ab96-e330819e2c07
        schema:
          type: string
      responses:
        '200':
          description: Order is already cancelled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/cancel_order_request_status_cancelled'
        '202':
          description: 'Order was successfully queued for cancellation.


            The `check_after` field indicates when you should expect a decision to be made regarding cancellation. You can call the corresponding GET endpoint after this timestamp to see the resulting status.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/cancel_order_request_status_pending'
        '400':
          description: Bad Request
        '403':
          description: You do not have permission to execute this operation.
        '404':
          description: Order does not exist or does not have an associated Virtual Credit Card Settlement.
        '503':
          description: Service unavailable
      tags:
      - Merchant Card
    get:
      summary: Klarna Get order cancellation status
      description: Get the status of an order cancellation request. The order must have an associated Virtual Credit Card Settlement.
      operationId: getcancelorder
      parameters:
      - name: order_id
        in: path
        description: Order id for which to view its cancellation status. This order must have an associated Virtual Credit Card Settlement.
        required: true
        example: f3392f8b-6116-4073-ab96-e330819e2c07
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved the status of the cancellation request for this order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/cancel_order_request_status'
        '400':
          description: Bad Request, or the order was not previously requested for cancellation by calling the POST endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/cancel_order_request_status_no_request_found'
        '403':
          description: You do not have permission to execute this operation.
        '404':
          description: Order does not exist or does not have an associated Virtual Credit Card Settlement.
        '503':
          description: Service unavailable
      tags:
      - Merchant Card
components:
  schemas:
    card_specification:
      type: object
      required:
      - amount
      - currency
      - reference
      properties:
        amount:
          type: integer
          format: int64
          example: 10000
          description: The total purchase amount on a card
          minimum: 1
        currency:
          type: string
          example: USD
          description: The amount currency
        fund_amount:
          type: integer
          format: int64
          example: 10000
          description: The funded amount that will be on a card
        reference:
          type: string
          example: yPGw6i4lR0GTcyxGpS3Q6Q==
          description: Your reference on the card
          minLength: 1
          maxLength: 255
    cancel_order_request_status_no_request_found:
      type: object
      required:
      - status
      - reason_code
      - reason_message
      properties:
        status:
          type: string
          example: NO_REQUEST_FOUND
          enum:
          - NO_REQUEST_FOUND
          description: The status of the order cancellation request.
        reason_code:
          type: string
          example: NO_REQUEST_FOUND
          enum:
          - NO_REQUEST_FOUND
          description: Reason code for the bad request.
        reason_message:
          type: string
          example: No cancellation request found for this order.
          description: Human-readable message for the bad request.
    promise_created_response:
      type: object
      properties:
        expires_at:
          type: string
          format: date-time
        promise_id:
          type: string
          example: ee4a8e3a-9dfd-49e0-9ac8-ea2b6c76408c
          description: The unique promise id
          readOnly: true
    settlement_response:
      type: object
      properties:
        settlement_id:
          type: string
          example: b0ec0bbd-534c-4b1c-b28a-628bf33c3324
          description: Unique settlement identifier.
        promise_id:
          type: string
          example: ee4a8e3a-9dfd-49e0-9ac8-ea2b6c76408c
          description: Unique identifier for the promise associated to the settlement.
        order_id:
          type: string
          example: f3392f8b-6116-4073-ab96-e330819e2c07
          description: Unique identifier for the order associated to the settlement.
        cards:
          type: array
          description: An array of Card objects.
          items:
            $ref: '#/components/schemas/card'
        created_at:
          type: string
          example: '2018-12-03T10:26:06.000Z'
          description: Settlement creation datetime (ISO 8601).
        expires_at:
          type: string
          example: '2018-12-04T10:26:06.000Z'
          description: Settlement expiration datetime (ISO 8601).
    settlement_request:
      type: object
      required:
      - key_id
      - order_id
      properties:
        promise_id:
          type: string
          example: ee4a8e3a-9dfd-49e0-9ac8-ea2b6c76408c
          description: Unique identifier for the promise associated to the settlement.
        order_id:
          type: string
          example: f3392f8b-6116-4073-ab96-e330819e2c07
          description: Unique identifier for the order associated to the settlement.
        key_id:
          type: string
          example: 16e4b85e-899b-4427-a39f-07a496e9515b
          description: Unique identifier for the public key to be used for encryption of the card data.
    promise_request:
      type: object
      required:
      - cards
      - order_id
      properties:
        order_id:
          type: string
          example: f3392f8b-6116-4073-ab96-e330819e2c07
          description: A valid order id
        cards:
          type: array
          description: The cards you would like to issue (max 1000)
          items:
            $ref: '#/components/schemas/card_specification'
          maxItems: 1000
          minItems: 1
    promise_response:
      type: object
      properties:
        promise_id:
          type: string
          example: ee4a8e3a-9dfd-49e0-9ac8-ea2b6c76408c
          description: The unique promise ID
          readOnly: true
        order_id:
          type: string
          example: f3392f8b-6116-4073-ab96-e330819e2c07
          description: The order id of the promise
          readOnly: true
        cards:
          type: array
          description: 'The list of card specifications '
          readOnly: true
          items:
            $ref: '#/components/schemas/card_specification'
        created_at:
          type: string
          format: date-time
          example: '2018-12-03T10:26:06.000Z'
          description: The time when the promise was created
          readOnly: true
        expire_at:
          type: string
          format: date-time
          example: '2018-12-04T10:26:06.000Z'
          description: The time when the promise expires
          readOnly: true
    card:
      type: object
      properties:
        reference:
          type: string
          example: yPGw6i4lR0GTcyxGpS3Q6Q==
          description: Identifier to reference order line.
        card_id:
          type: string
          example: b846430c-3656-43a1-812e-2ccff4531b7d
          description: Unique card identifier.
        amount:
          type: integer
          format: int64
          example: 10000
          description: The total amount available on the card. In minor units. The number of decimals are controlled by the currency.
        currency:
          type: string
          example: USD
          description: The ISO 4217 code states which currency it is and how many decimals the amount has.
        pci_data:
          type: string
          description: Encrypted, PCI compliant card data.
        iv:
          type: string
          description: Initialization vector for symmetric decryption with the AES key.
        aes_key:
          type: string
          description: The symmetric key complying the Advanced Encryption Standard.
        brand:
          type: string
          example: VISA
          description: The brand of the card.
        holder:
          type: string
          example: Jane Doe
          description: Card holder name on the card.
    cancel_order_request_status_cancelled:
      type: object
      required:
      - status
      properties:
        status:
          type: string
          example: CANCELLED
          enum:
          - CANCELLED
          description: The status of the order cancellation request.
    cancel_order_request_status_pending:
      type: object
      required:
      - status
      - check_after
      properties:
        status:
          type: string
          example: PENDING
          enum:
          - PENDING
          description: The status of the order cancellation request.
        check_after:
          type: string
          format: date-time
          example: '2018-12-04T10:26:06.000Z'
          description: Timestamp for when we expect a decision to be made on order cancellation. (ISO 8601)
    cancel_order_request_status:
      type: object
      required:
      - status
      properties:
        status:
          type: string
          example: PENDING
          enum:
          - PENDING
          - CANCELLED
          - REJECTED
          description: The status of the order cancellation request.
        check_after:
          type: string
          format: date-time
          example: '2018-12-04T10:26:06.000Z'
          description: 'Timestamp for when we expect a decision to be made on order cancellation. (ISO 8601)


            This field is only populated if status is `PENDING`.'
        reason_code:
          type: string
          example: CARD_IN_USE
          enum:
          - CARD_IN_USE
          - OTHER
          description: 'Reason code for why the order cancellation was rejected.


            This field is only populated if status is `REJECTED`.'
        reason_message:
          type: string
          example: Cancellation request was rejected because the virtual credit card linked to this order is in use.
          description: 'Human-readable message for why the order cancellation was rejected.


            This field is only populated if status is `REJECTED`.'