API & SDKsSupport

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 
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 
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 
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 
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 
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