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.

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

Payload
curl
JavaScript
Node.js

application/json

{"order_id": "f3392f8b-6116-4073-ab96-e330819e2c07",
"cards": [{"amount": 10000,
"currency": "USD",
"fund_amount": 10000,
"reference": "yPGw6i4lR0GTcyxGpS3Q6Q=="
}
]
}

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
JavaScript
Node.js

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": [{"amount": 10000,
"currency": "USD",
"fund_amount": 10000,
"reference": "yPGw6i4lR0GTcyxGpS3Q6Q=="
}
],
"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

Payload
curl
JavaScript
Node.js

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": [{"reference": "yPGw6i4lR0GTcyxGpS3Q6Q==",
"card_id": "b846430c-3656-43a1-812e-2ccff4531b7d",
"amount": 10000,
"currency": "USD",
"pci_data": "string",
"iv": "string",
"aes_key": "string",
"brand": "VISA",
"holder": "Jane Doe"
}
],
"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
JavaScript
Node.js

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": [{"reference": "yPGw6i4lR0GTcyxGpS3Q6Q==",
"card_id": "b846430c-3656-43a1-812e-2ccff4531b7d",
"amount": 10000,
"currency": "USD",
"pci_data": "string",
"iv": "string",
"aes_key": "string",
"brand": "VISA",
"holder": "Jane Doe"
}
],
"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
JavaScript
Node.js

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": [{"reference": "yPGw6i4lR0GTcyxGpS3Q6Q==",
"card_id": "b846430c-3656-43a1-812e-2ccff4531b7d",
"amount": 10000,
"currency": "USD",
"pci_data": "string",
"iv": "string",
"aes_key": "string",
"brand": "VISA",
"holder": "Jane Doe"
}
],
"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
JavaScript
Node.js

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
JavaScript
Node.js

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."
}