Merchant Card Service API (1.0.0)

Download OpenAPI specification:Download

The Merchant Card Service (MCS) API is used to settle orders with virtual credit cards.

Read more on Merchant card service.

Create a card promise

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

Request
Request Body schema: application/json
order_id
required
string

A valid order id

required
Array of objects (card_specification) [ 1 .. 1000 ] items

The cards you would like to issue (max 1000)

Responses
201

successful operation

400

Bad Request

503

Service unavailable

post/merchantcard/v3/promises
Request samples
application/json
{
  • "order_id": "f3392f8b-6116-4073-ab96-e330819e2c07",
  • "cards": [
    ]
}
Response samples
application/json
{
  • "expires_at": "2019-08-24T14:15:22Z",
  • "promise_id": "ee4a8e3a-9dfd-49e0-9ac8-ea2b6c76408c"
}

Get details of a card promise

To get the promise resource simply provide a promise identifier.

Request
path Parameters
promise_id
required
string
Example: ee4a8e3a-9dfd-49e0-9ac8-ea2b6c76408c
Responses
200

successful operation

403

Forbidden

404

Not found

get/merchantcard/v3/promises/{promise_id}
Request samples
curl -i -X GET \
  'https://api.klarna.com/merchantcard/v3/promises/{promise_id}'
Response samples
application/json
{
  • "promise_id": "ee4a8e3a-9dfd-49e0-9ac8-ea2b6c76408c",
  • "order_id": "f3392f8b-6116-4073-ab96-e330819e2c07",
  • "cards": [
    ],
  • "created_at": "2018-12-03T10:26:06.000Z",
  • "expire_at": "2018-12-04T10:26:06.000Z"
}

Create a card settlement

To create a settlement resource provide a completed order identifier and (optionally) a promise identifier.

Request
Request Body schema: application/json
promise_id
string

Unique identifier for the promise associated to the settlement.

order_id
required
string

Unique identifier for the order associated to the settlement.

key_id
required
string

Unique identifier for the public key to be used for encryption of the card data.

Responses
201

successful operation

400

Bad Request

403

Forbidden

503

Service unavailable

post/merchantcard/v3/settlements
Request samples
application/json
{
  • "promise_id": "ee4a8e3a-9dfd-49e0-9ac8-ea2b6c76408c",
  • "order_id": "f3392f8b-6116-4073-ab96-e330819e2c07",
  • "key_id": "16e4b85e-899b-4427-a39f-07a496e9515b"
}
Response samples
application/json
{
  • "settlement_id": "b0ec0bbd-534c-4b1c-b28a-628bf33c3324",
  • "promise_id": "ee4a8e3a-9dfd-49e0-9ac8-ea2b6c76408c",
  • "order_id": "f3392f8b-6116-4073-ab96-e330819e2c07",
  • "cards": [
    ],
  • "created_at": "2018-12-03T10:26:06.000Z",
  • "expires_at": "2018-12-04T10:26:06.000Z"
}

Get details of card settlement

To get the settlement resource provide the settlement identifier.

Request
path Parameters
settlement_id
required
string

Unique settlement identifier.

Example: b0ec0bbd-534c-4b1c-b28a-628bf33c3324
header Parameters
KeyId
required
string

Unique identifier for the public key used for encryption of the card data.

Responses
200

successful operation

403

Forbidden

404

Not Found

get/merchantcard/v3/settlements/{settlement_id}
Request samples
curl -i -X GET \
  'https://api.klarna.com/merchantcard/v3/settlements/{settlement_id}' \
  -H 'KeyId: string'
Response samples
application/json
{
  • "settlement_id": "b0ec0bbd-534c-4b1c-b28a-628bf33c3324",
  • "promise_id": "ee4a8e3a-9dfd-49e0-9ac8-ea2b6c76408c",
  • "order_id": "f3392f8b-6116-4073-ab96-e330819e2c07",
  • "cards": [
    ],
  • "created_at": "2018-12-03T10:26:06.000Z",
  • "expires_at": "2018-12-04T10:26:06.000Z"
}

Get card settlement details for an order

To get the order's settlement resource provide the order identifier.

Request
path Parameters
order_id
required
string

Unique identifier for the order associated to the settlement.

Example: f3392f8b-6116-4073-ab96-e330819e2c07
header Parameters
KeyId
required
string

Unique identifier for the public key used for encryption of the card data.

Responses
200

successful operation

403

Forbidden

404

Not Found

get/merchantcard/v3/settlements/order/{order_id}
Request samples
curl -i -X GET \
  'https://api.klarna.com/merchantcard/v3/settlements/order/{order_id}' \
  -H 'KeyId: string'
Response samples
application/json
{
  • "settlement_id": "b0ec0bbd-534c-4b1c-b28a-628bf33c3324",
  • "promise_id": "ee4a8e3a-9dfd-49e0-9ac8-ea2b6c76408c",
  • "order_id": "f3392f8b-6116-4073-ab96-e330819e2c07",
  • "cards": [
    ],
  • "created_at": "2018-12-03T10:26:06.000Z",
  • "expires_at": "2018-12-04T10:26:06.000Z"
}

Request order cancellation

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.

Request
path Parameters
order_id
required
string

Order id you wish to cancel. This order must have an associated Virtual Credit Card Settlement.

Example: f3392f8b-6116-4073-ab96-e330819e2c07
Responses
200

Order is already cancelled.

202

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.

400

Bad Request

403

You do not have permission to execute this operation.

404

Order does not exist or does not have an associated Virtual Credit Card Settlement.

503

Service unavailable

post/merchantcard/v3/orders/{order_id}/cancel-request
Request samples
curl -i -X POST \
  'https://api.klarna.com/merchantcard/v3/orders/{order_id}/cancel-request'
Response samples
application/json
{
  • "status": "CANCELLED"
}

Get order cancellation status

Get the status of an order cancellation request. The order must have an associated Virtual Credit Card Settlement.

Request
path Parameters
order_id
required
string

Order id for which to view its cancellation status. This order must have an associated Virtual Credit Card Settlement.

Example: f3392f8b-6116-4073-ab96-e330819e2c07
Responses
200

Successfully retrieved the status of the cancellation request for this order.

400

Bad Request, or the order was not previously requested for cancellation by calling the POST endpoint.

403

You do not have permission to execute this operation.

404

Order does not exist or does not have an associated Virtual Credit Card Settlement.

503

Service unavailable

get/merchantcard/v3/orders/{order_id}/cancel-request
Request samples
curl -i -X GET \
  'https://api.klarna.com/merchantcard/v3/orders/{order_id}/cancel-request'
Response samples
application/json
{
  • "status": "PENDING",
  • "check_after": "2018-12-04T10:26:06.000Z",
  • "reason_code": "CARD_IN_USE",
  • "reason_message": "Cancellation request was rejected because the virtual credit card linked to this order is in use."
}
Cookies
Terms of Service
© Klarna 2024