Skip to main content
Versionv1.15.0
API docs by Redocly

Merchant API (1.15.0)

Download OpenAPI specification:Download

Development: [email protected] URL: https://www.cm.com

Payment Acceptance Made Easy

The MerchantAPI allows merchants to interact with and retrieve information from the PayPlaza payment system. It allows merchants to retrieve information about how their account has been setup with Stores and Terminals. It allows merchants to retrieve the list and the details of Transactions and it allows merchants to initiate a new Payment.

Errors

Error responses, HTTP status 400 and higher, will contain a JSON response body with details about the error. We follow the error response format proposed in RFC 7807 also known as Problem Details for HTTP APIs. As with our normal API responses, your client must be prepared to gracefully handle additional members of the response.

Note: Problem type and instance identifiers in our APIs are not meant to be resolved. RFC 7807 encourages that problem types are URI references that point to human-readable documentation, but we deliberately decided against that, as all important parts of the API are documented.

Security

For managing API keys

Retrieve details about the available APIKeys

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create new API key

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
label
required
string
object or null

Responses

Request samples

Content type
application/json
{
  • "label": "string",
  • "validity": {
    }
}

Response samples

Content type
application/json
{
  • "id": "stringstringstr",
  • "label": "string",
  • "apikey": "stringstringstringstringstringstringstringstringst"
}

Delete an API key

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/problem+json
{}

Stores

Operations related to stores

List all stores.

Authorizations:
ApiKeyAuth
query Parameters
page
integer <int32> >= 1
Default: 1

The page number of your query result

size
integer <int32> [ 1 .. 100 ]
Default: 10

The amount of results (defaults to 10)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List all stores with their assigned devices.

Authorizations:
ApiKeyAuth
query Parameters
page
integer <int32> >= 1
Default: 1

The page number of your query result

size
integer <int32> [ 1 .. 100 ]
Default: 10

The amount of results (defaults to 10)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Terminals

Operations related to terminals

List all terminals.

Authorizations:
ApiKeyAuth
query Parameters
page
integer <int32> >= 1
Default: 1

The page number of your query result, starting at 1

size
integer <int32> [ 1 .. 100 ]
Default: 10

The amount of results per page, maximum 100 (defaults to 10)

category
string or null

Filter on terminal category. Possible values: ALL (default, all terminals), CLOUD (only terminals with Cloud Integration))

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get terminal by manufacturer, model & serial.

Authorizations:
ApiKeyAuth
path Parameters
manufacturer
required
string [ 1 .. 255 ] characters

Manufacturer name of the terminal

model
required
string [ 1 .. 255 ] characters

Model name of the terminal

serial
required
string [ 1 .. 255 ] characters

Serial(number) of the terminal

Responses

Response samples

Content type
application/json
{
  • "device": {
    }
}

Get the day totals for the terminal by manufacturer, model & serial.

Authorizations:
ApiKeyAuth
path Parameters
manufacturer
required
string [ 1 .. 255 ] characters

Manufacturer name of the terminal

model
required
string [ 1 .. 255 ] characters

Model name of the terminal

serial
required
string [ 1 .. 255 ] characters

Serial(number) of the terminal

Responses

Response samples

Content type
application/json
{
  • "receipt": "string"
}

List transactions by terminal.

Authorizations:
ApiKeyAuth
path Parameters
manufacturer
required
string [ 1 .. 255 ] characters

Manufacturer name of the terminal

model
required
string [ 1 .. 255 ] characters

Model name of the terminal

serial
required
string [ 1 .. 255 ] characters

Serial(number) of the terminal

query Parameters
page
integer <int32> >= 1
Default: 1

The page number of your query result, starting at 1

size
integer <int32> [ 1 .. 100 ]
Default: 10

The amount of results per page, maximum 100 (defaults to 10)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create new transaction for terminal.

The Merchant-API will make sure only one newly created transaction is available for a specific terminal. This means that when creating a new transaction, previous transaction(s) with status CREATED will be aborted. So given transactions A and B, when transaction A has not been retrieved by the terminal when creating transaction B the Merchant API will abort transaction A, and the terminal will receive transaction B.

Authorizations:
ApiKeyAuth
path Parameters
manufacturer
required
string [ 1 .. 255 ] characters

Manufacturer name of the terminal

model
required
string [ 1 .. 255 ] characters

Model name of the terminal

serial
required
string [ 1 .. 255 ] characters

Serial(number) of the terminal

Request Body schema: application/json
required
merchant_order_reference
required
string [ 1 .. 14 ] characters ([0-9a-zA-Z]|-|_){1,14}

Reference provided by the Merchant for future identification of this Transaction
This field may contain all letters in lowercase and uppercase, digit, underscore '_' and hyphen-minus '-'Usually a unique identifier generated by the Merchant

type
required
string (TransactionType)
Enum: "PURCHASE" "PRE_AUTH" "REFUND" "CNP_REFUND" "PURCHASE_MAT"
PURCHASE
Indicates a purchase where the money will flow from the consumer to the merchant
PRE_AUTH
Indicates a claim on a certain amount of money on the bankaccount of the consumer
REFUND
Indicates a refunds where the money will flow from the merchant back to the consumer
CNP_REFUND
Indicates a refunds where the money will flow from the merchant back - card not present
PURCHASE_MAT
Indicates a purchase where the money will flow from the consumer to the merchant
required
object (Amount)

Describes how much money the transaction should be.
'value' is a number value with a dot (.) as decimal separator. It should NOT have any digit grouping or thousands separators
'currency' is a 3-letter-code, compliant with ISO 4217

object or null

Reference object that represents a unique identifier for a transaction

Responses

Request samples

Content type
application/json
Example
{
  • "type": "PURCHASE",
  • "merchant_order_reference": "1234",
  • "amount": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "creation_datetime": "2022-01-19T12:58:00Z",
  • "merchant_order_reference": "Q99PM-2QHFW-FQ",
  • "brand": "string",
  • "system_trace_audit_number": "string",
  • "receipt": "string",
  • "original_id": "string",
  • "authorization_code": "string",
  • "merchant_id": "string",
  • "processor_terminal_id": "string",
  • "type": "PURCHASE",
  • "amount": {
    },
  • "store": {
    },
  • "merchant_receipt": "string",
  • "result": "APPROVED",
  • "status": "CREATED"
}

Get transaction by terminal and id.

Authorizations:
ApiKeyAuth
path Parameters
manufacturer
required
string [ 1 .. 255 ] characters

Manufacturer name of the terminal

model
required
string [ 1 .. 255 ] characters

Model name of the terminal

serial
required
string [ 1 .. 255 ] characters

Serial(number) of the terminal

id
required
string = 31 characters [0-9]{31}

Identifier of a transaction

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "creation_datetime": "2022-01-19T12:58:00Z",
  • "merchant_order_reference": "Q99PM-2QHFW-FQ",
  • "brand": "string",
  • "system_trace_audit_number": "string",
  • "receipt": "string",
  • "original_id": "string",
  • "authorization_code": "string",
  • "merchant_id": "string",
  • "processor_terminal_id": "string",
  • "type": "PURCHASE",
  • "amount": {
    },
  • "store": {
    },
  • "merchant_receipt": "string",
  • "result": "APPROVED",
  • "status": "CREATED"
}

Abort a transaction by terminal and id.

Authorizations:
ApiKeyAuth
path Parameters
manufacturer
required
string [ 1 .. 255 ] characters

Manufacturer name of the terminal

model
required
string [ 1 .. 255 ] characters

Model name of the terminal

serial
required
string [ 1 .. 255 ] characters

Serial(number) of the terminal

id
required
string = 31 characters [0-9]{31}

Identifier of a transaction

Responses

Response samples

Content type
application/problem+json
{}

Version

Retrieves system information

Retrieving the system version.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/problem+json
{}

cnp

Card not present operations

List CNP transactions 

        Retrieve a paginated list of CNP transactions for the authenticated organization.
        Returns CNP transactions from the last 90 days based on data retention policy.
Authorizations:
ApiKeyAuth
query Parameters
page
required
integer >= 1
Default: 1

Page number (1-based)

size
required
integer [ 1 .. 100 ]
Default: 10

Page size

Responses

Response samples

Content type
application/json
{
  • "currentPage": null,
  • "currentPageIndex": 0,
  • "pageCount": 0,
  • "totalCount": 0,
  • "pageSize": 0
}

Get CNP day totals for today 

        Retrieves the day totals receipt for CNP transactions for the authenticated organization.
        Returns totals from midnight (00:00) of the current day by default.
        Optionally, you can specify a start time to filter transactions from a specific hour.
Authorizations:
ApiKeyAuth
query Parameters
hourFrom
required
integer or null [ 0 .. 23 ]

Starting hour (0-23). Defaults to 0 (midnight)

minuteFrom
required
integer or null [ 0 .. 59 ]

Starting minute (0-59). Defaults to 0

Responses

Response samples

Content type
application/problem+json
{}

Retrieve CNP transaction by ID 

        Retrieve the status and details of a specific CNP (Card Not Present) transaction.
        Only transactions of type CNP_REFUND are supported.
Authorizations:
ApiKeyAuth
path Parameters
cnpTransactionId
required
string [ 1 .. 255 ] characters

CNP transaction identifier

Responses

Response samples

Content type
application/json
{
  • "merchant_order_reference": "656",
  • "amount": {
    },
  • "store": {
    },
  • "id": "0001012025091810182125600000004",
  • "system_trace_audit_number": "100123",
  • "brand": "VISA",
  • "receipt": " Certification Store \n eMerchantpay example",
  • "result": "APPROVED",
  • "status": "CLEARED",
  • "creation_datetime": "2025-09-18T08:18:16Z",
  • "merchant_id": "180ad3fe-f192-49ba-a5e7-8f09718f651c",
  • "type": "CNP_REFUND",
  • "authorization_code": "148490"
}

Create new card not present refund. 

        The Merchant-API ensures that only one CNP refund is created and processed per transaction (purchase).
        The terminal is not part of this refund flow.
Authorizations:
ApiKeyAuth
path Parameters
transactionId
required
string [ 1 .. 255 ] characters

Original transaction identifier

Request Body schema: application/json
required
transactionId
required
string[0-9]{31}
            Unique identifier generated by PayPlaza for this transaction.
            Format will be 31 numeric characters.
status
required
string([0-9a-zA-Z]|-|_){1,14}

Result of the operation

merchantOrderReference
required
string
required
object (Amount)

Describes how much money the transaction should be.
'value' is a number value with a dot (.) as decimal separator. It should NOT have any digit grouping or thousands separators
'currency' is a 3-letter-code, compliant with ISO 4217

Responses

Request samples

Content type
application/json
{
  • "merchant_order_reference": "1234",
  • "amount": {
    }
}

Response samples

Content type
application/json
{
  • "transactionId": "string",
  • "status": "FAILED - SUCCESS",
  • "merchantOrderReference": "string",
  • "amount": {
    }
}