# CloudPos

Sending commands to the POS terminal.

Endpoint: POST /cloudpos
Version: 2.2.0
Security: bearerAuth, basicAuth

## 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.value` (number)

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

## Response 201 fields (application/json):

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

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

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

  - `refNr` (string)
    Dealer reference number.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  - `dcc` (object)

  - `dcc.foreignAmount` (number)
    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.

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

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

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

  - `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)
    Echoed from the request parameter.

  - `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.brand` (string)
    Brand: VISA, MASTERCARD, MAESTRO, AMEX, DINERS, JCB, CUP.

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

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

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

  - `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 fields (application/json):

  - `type` (string)
    A URI reference that identifies the problem type
    Example: "https://tools.ietf.org/html/rfc9110#section-15.5.1"

  - `title` (string)
    A short, human-readable summary of the problem type
    Example: "One or more validation errors occurred."

  - `status` (integer)
    The HTTP status code
    Example: 400

  - `traceId` (string)
    Trace Id
    Example: "00-a06284de9126d7fa46a5d112b3a721c3-c923572965eea46b-00"

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

## Response 422 fields (application/json):

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

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

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

  - `refNr` (string)
    Dealer reference number.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  - `dcc` (object)

  - `dcc.foreignAmount` (number)
    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.

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

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

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

  - `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)
    Echoed from the request parameter.

  - `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.brand` (string)
    Brand: VISA, MASTERCARD, MAESTRO, AMEX, DINERS, JCB, CUP.

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

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

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

  - `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 500 fields (application/json):

  - `responseCode` (string)
    Example: "A specific identifier for the error cause"

  - `responseDescription` (string)
    Example: "A brief message explaining the error"