# CloudPos

Sending commands to the POS terminal.

Endpoint: POST /cloudpos
Version: 2.7.0
Security: bearer, basic, apiKey

## Security:

  - `bearer` (unknown)
    http bearer JWT

  - `basic` (unknown)
    http basic

  - `apiKey` (unknown)
    apiKey in header X-API-Key

## Header parameters:

  - `Idempotency-Key` (string)
    A unique key provided by you to ensure that a particular operation is not processed multiple times in case of retries.

## Request fields (application/json):

  - `transId` (string, required)
    Transaction ID created in your system. It should be unique for each payment.

  - `messageType` (string, required)
    Defines the type of payment: Supported values are: 01 - Sale; 02 - Reverse; 03 - Credit; 05 - Authorization/Reservation; 0B - Capture; 0C - Card Read; 0D - Diagnose; A1 - Terminal Startup.
    Enum: "SALE", "REVERSE", "CREDIT", "AUTHORISATION_OR_RESERVATION", "CAPTURE", "CARD_READ", "DIAGNOSE", "TERMINAL_STARTUP"

  - `refNr` (string)
    Your unique reference number for the specific operation. You can pass this value to reconcile different operations in a payment (authorization, capture, refund, etc) individually.

  - `amount` (object, required)
    Amount object of the payment plan.

  - `amount.value` (integer)
    Total order amount in the smallest currency unit, including taxes, shipping costs, discounts, etc.

  - `amount.currency` (string)
    3-character ISO currency code.

  - `posTerminalId` (string, required)
    TerminalID of PIN entry device.

  - `cardReadMode` (string)
    Defines the technology to be used to read the card. Valid values are: msr.
    Enum: "MSR"

  - `localDateTime` (string, required)
    Transaction date and time.

  - `traceNr` (string)
    Mandatory for subsequent functions Reversal or Capture (MessageType=02/08). It must be equal to the value traceNr received from the original authorization response. Merchant POS system must provide this in the request.

  - `approvalCode` (string)
    Mandatory for subsequent function Capture (MessageType=08). It must be equal to the value approvalCode received from the original authorization response. Merchant POS system must provide this in the request.

  - `credentialOnFile` (object)

  - `credentialOnFile.type` (string)
    Indicates the type of credential-on-file transaction.
    Enum: "RECURRING", "UNSCHEDULED"

  - `credentialOnFile.initialPayment` (boolean)
    Specifies whether the transaction is the initial payment in a credential-on-file setup.

  - `credentialOnFile.unscheduled` (object)

  - `credentialOnFile.unscheduled.subType` (string)
    Specifies the sub-type of an unscheduled credential-on-file transaction.
    Enum: "CIT"

  - `contractId` (string)
    Special merchant ID at the acquirer to overrule the default merchant ID.

## Request examples:

  - `Example` (unknown)

## Response 201:

  - `201` (unknown)
    Created

## Response 201 fields (application/json):

  - `status` (string)
    OK (URLSuccess) or FAILED (URLFailure).

  - `responseCode` (string)
    Response code of the transaction.

  - `responseDescription` (string)
    Response description associated with the response code.

  - `refNr` (string)
    Dealer reference number.

  - `payId` (string)
    A unique identifier assigned by Computop Paygate to the payment. This ID remains constant throughout the lifecycle of the payment and is used to track and reference the payment across all subsequent operations, such as authorization, capture, refund, or cancellation.

  - `merchantId` (string)
    Merchant ID assigned by Computop.

  - `transId` (string)
    Your own transaction ID, which must be unique for each payment.

  - `contractId` (string)
    Echoed from the request parameter.

  - `terminalId` (string)
    Terminal ID which is forwarded towards acquirer authorization host.

  - `posTerminalId` (string)
    Echoed from the request parameter.

  - `providerResponseCode` (string)
    Financial transaction Authorization Host response code (Payment).

  - `traceNr` (string)
    Trace number. Merchant must save this value form the response and use it when referencing subsequent actions i.e Reverse, Capture.

  - `vuNr` (string)
    Acquirer Contract ID number on which the transaction was processed.

  - `additionalResponseData` (string)
    Additional text which the operator’s processing system can send optionally in replies to payment/cutover requests.

  - `approvalCode` (string)
    Approval code from authorization host in the response message to the client. Only in case of successful credit card transactions. Merchant must save this value form the response and use it when referencing Capture subsequent action.

  - `localDateTime` (string)
    Transaction date and time.

  - `aidParameters` (string)
    Authorisation parameters: if these are present, the authorisation parameters must be printed out on the terminal receipt in unpacked form as 10 hexadecimal numbers. Aid-parameters can contain up to 130 characters for electronic cash payments.

  - `verificationCode` (string)
    Used authentication mode. Possible values: Signature; PIN; On consumer device; NoAuth.

  - `receipt` (object)
    Data containing the receipt information which can be printed out by the merchant system.

  - `receipt.receiptNr` (string)
    Receipt number.

  - `receipt.receiptMerchant` (string)
    Merchant Receipt data.

  - `receipt.receiptCustomer` (string)
    Customer Receipt data.

  - `receipt.receiptCopies` (integer)
    Number of receipt copies to be printed.

  - `receipt.receiptsNumber` (integer)
    Receipts number.

  - `dcc` (object)

  - `dcc.foreignAmount` (integer)
    Applicable for DCC transactions.

  - `dcc.foreignCurrencyCode` (string)
    Applicable for DCC transactions.

  - `dcc.commission` (string)
    Applicable for DCC transactions.

  - `dcc.margin` (string)
    Applicable for DCC transactions.

  - `dcc.rateValue` (string)
    Applicable for DCC transactions.

  - `dcc.source` (string)
    Applicable for DCC transactions.

  - `dcc.timestamp` (string)
    Applicable for DCC transactions.

  - `dcc.disclaimerText` (string)
    Applicable for DCC transactions.

  - `credentialOnFile` (object)

  - `credentialOnFile.type` (string)
    Indicates the type of credential-on-file transaction.
    Enum: "RECURRING", "UNSCHEDULED"

  - `credentialOnFile.initialPayment` (boolean)
    Specifies whether the transaction is the initial payment in a credential-on-file setup.

  - `credentialOnFile.unscheduled` (object)

  - `credentialOnFile.unscheduled.subType` (string)
    Specifies the sub-type of an unscheduled credential-on-file transaction.
    Enum: "CIT"

  - `paymentMethod` (object)

  - `paymentMethod.card` (object)

  - `paymentMethod.card.fist6Digits` (string)
    First 6 digits of card. Present only for successful transactions.

  - `paymentMethod.card.last4Digits` (string)
    Last 4 digits of card. Present only for successful transactions.

  - `paymentMethod.card.cardSequenceNumber` (string)
    Card sequence number.

  - `paymentMethod.card.brand` (string)
    Brand: VISA, MASTERCARD, MAESTRO, AMEX, DINERS, JCB, CUP.

  - `paymentMethod.card.pseudoCardNumber` (string)
    Pseudo Card Number.

  - `paymentMethod.card.expiryDate` (string)
    Expiry date of the card in YYYYMM format.

  - `paymentMethod.card.schemeReferenceId` (string)
    Identifier assigned by schemes to the transaction.

  - `paymentMethod.directDebit` (object)

  - `paymentMethod.directDebit.accountNumber` (string)
    Masked Bank account number for EC transactions.

## Response 400:

  - `400` (unknown)
    Bad request, [https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400)

## Response 400 fields (application/json):

  - `errors` (object)
    "Object": [
"Error 1",
"Error 2"
]
}`

  - `type` (string)
    A URI reference that identifies the problem type

  - `title` (string)
    A short, human-readable summary of the problem type

  - `status` (string)
    The HTTP status code

  - `detail` (string)

  - `instance` (string)

## Response 422:

  - `422` (unknown)
    Unprocessable Entity, [https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422)

## Response 422 fields (application/json):

  - `merchantId` (string)
    Merchant ID assigned by Computop Paygate.

  - `payId` (string)
    A unique identifier assigned by Computop Paygate to the payment. This ID remains constant throughout the lifecycle of the payment and is used to track and reference the payment across all subsequent operations, such as authorization, capture, refund, or cancellation.

  - `xId` (string)
    A unique identifier assigned by Computop Paygate for each operation in the payment. For example: xId will be different for the authorization and capture operations of a payment whereas payId will be same.

  - `transId` (string)
    Transaction ID provided by you in the request.

  - `refNr` (string)
    Reference number provided by you in the request.

  - `responseCode` (string)
    Response code of the transaction.

  - `responseDescription` (string)
    Response description associated with the response code.

  - `paymentPlanId` (string)

  - `paymentMethods` (object)

  - `paymentMethods.amazonPay` (object)

  - `paymentMethods.amazonPay.providerStatus` (string)

  - `paymentMethods.amazonPay.providerResponseText` (string)

  - `paymentMethods.amazonPay.providerResponseCode` (string)

  - `paymentMethods.card` (object)

  - `paymentMethods.card.providerResponseCode` (string)
    Returned only when Acquirer is Clearhaus or MasaPay.

  - `paymentMethods.card.providerResponseText` (string)
    Returned only when Acquirer is Clearhaus or MasaPay. Information is passed only when status is FAILED.

  - `paymentMethods.card.issuerResponseCode` (string)
    Issuer response code.

  - `paymentMethods.card.issuerResponseMessage` (string)
    Issuer response text.

  - `paymentMethods.directDebit` (object)

  - `paymentMethods.directDebit.providerResponseCode` (string)
    Provider response code.

  - `paymentMethods.directDebit.providerResponseText` (string)
    Provider response text.

  - `paymentMethods.easyCollect` (object)

  - `paymentMethods.easyCollect.providerResponseCode` (string)
    Provider response code.

  - `paymentMethods.easyCollect.providerResponseText` (string)
    Provider response text.

  - `paymentMethods.eps` (object)

  - `paymentMethods.eps.providerResponseText` (string)
    Is returned only if Status=FAILED. Detailed PPRO error message.

  - `paymentMethods.bancontact` (object)

  - `paymentMethods.bancontact.providerResponseText` (string)

  - `paymentMethods.klarna` (object)

  - `paymentMethods.klarna.providerResponseCode` (string)
    Response code from Klarna	.

  - `paymentMethods.klarna.providerResponseText` (string)
    Response description from Klarna	.

  - `paymentMethods.ratepay` (object)

  - `paymentMethods.ratepay.providerDeclineCategory` (string)
    Decline category provider by Ratepay. See Decline Categories for details.

  - `paymentMethods.ratepay.providerResponseText` (string)
    A message from Ratepay describing which constraint was violated.

  - `paymentMethods.ratepay.providerResponseCode` (string)
    List of none, one or multiple reasons why the request was declined. See Decline Categories to learn about possible reasons for each decline category.

  - `paymentMethods.ratepay.providerTransactionId` (string)

  - `paymentMethods.payPal` (object)

  - `paymentMethods.payPal.providerResponseCode` (string)

  - `paymentMethods.wero` (object)

  - `paymentMethods.wero.providerResponseText` (string)

  - `paymentMethods.wero.providerResponseCode` (string)

  - `paymentMethods.riverty` (object)

  - `paymentMethods.riverty.providerResponseCode` (string)

  - `paymentMethods.riverty.providerResponseText` (string)

  - `type` (string)

  - `title` (string)

  - `status` (string)
    Status of the transaction.

  - `detail` (string)

  - `instance` (string)

## Response 500:

  - `500` (unknown)
    Internal Server Error, [https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500)

## Response 500 fields (application/json):

  - `type` (string)

  - `title` (string)

  - `status` (string)

  - `detail` (string)

  - `instance` (string)

## Response 201 examples:

  - `Default` (unknown)

## Response 422 examples:

  - `Default` (unknown)

