Skip to content

CloudPos

Use your web-based ERP or shop system to accept card payments in stationery businesses. The communication of your terminals at the point of sale occurs via the Internet directly through Computop Paygate and makes traditional interfaces such as OPI or ZVT superfluous.

Operations

CloudPos

Request

Sending commands to the POS terminal.

Security
bearer and basic and apiKey
Headers
Idempotency-Keystring

A unique key provided by you to ensure that a particular operation is not processed multiple times in case of retries.

Bodyapplication/jsonrequired
transIdstringrequired

Transaction ID created in your system. It should be unique for each payment.

messageTypestringrequired

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

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.

amountobject(amountMini)required

Amount object of the payment plan.

posTerminalIdstringrequired

TerminalID of PIN entry device.

cardReadModestring

Defines the technology to be used to read the card. Valid values are: msr.

Value:"MSR"
localDateTimestring, (date-time)required

Transaction date and time.

traceNrstring

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.

approvalCodestring

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.

credentialOnFileobject(credentialOnFileCloudPos)
contractIdstring

Special merchant ID at the acquirer to overrule the default merchant ID.

curl -i -X POST \
  -u '<username>:<password>' \
  https://test.computop-paygate.com/api/v2/cloudpos \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: string' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "transId": "435345423",
    "messageType": "SALE",
    "refNr": "42342344",
    "amount": {
      "value": 5000,
      "currency": "EUR"
    },
    "posTerminalId": "987654321",
    "cardReadMode": "MSR",
    "localDateTime": "2025-10-13T15:05:06",
    "traceNr": "3543534",
    "approvalCode": "T454353",
    "credentialOnFile": {
      "initialPayment": true,
      "type": "UNSCHEDULED",
      "unscheduled": {
        "subType": "CIT"
      }
    },
    "contractId": "overidden_merchantId"
  }'

Responses

Created

Bodyapplication/json
statusstring

OK (URLSuccess) or FAILED (URLFailure).

responseCodestring

Response code of the transaction.

responseDescriptionstring

Response description associated with the response code.

refNrstring

Dealer reference number.

payIdstring

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.

merchantIdstring

Merchant ID assigned by Computop.

transIdstring

Your own transaction ID, which must be unique for each payment.

contractIdstring

Echoed from the request parameter.

terminalIdstring

Terminal ID which is forwarded towards acquirer authorization host.

posTerminalIdstring

Echoed from the request parameter.

providerResponseCodestring

Financial transaction Authorization Host response code (Payment).

traceNrstring

Trace number. Merchant must save this value form the response and use it when referencing subsequent actions i.e Reverse, Capture.

vuNrstring

Acquirer Contract ID number on which the transaction was processed.

additionalResponseDatastring

Additional text which the operator’s processing system can send optionally in replies to payment/cutover requests.

approvalCodestring

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.

localDateTimestring, (date-time)

Transaction date and time.

aidParametersstring

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.

verificationCodestring

Used authentication mode. Possible values: Signature; PIN; On consumer device; NoAuth.

receiptobject(receipt)

Data containing the receipt information which can be printed out by the merchant system.

dccobject(dccCloudPos)
credentialOnFileobject(credentialOnFileCloudPos)
paymentMethodobject(paymentMethodCloudPos)
Response
{ "status": "OK", "responseDescription": "success", "refNr": "42342344", "payId": "234234-24524-2342-2324", "merchantId": "demo_test", "transId": "01TransIdTest", "contractId": "01ContractIDTest", "terminalId": "2342342", "posTerminalId": "82623104", "providerResponseCode": "201", "traceNr": "3543534", "vuNr": "10344", "additionalResponseData": "some additional data", "approvalCode": "T454353", "localDateTime": "2030-08-30T15:04:59", "aidParamaters": "5423423423423JDISOOS432423", "verificationCode": "PIN", "receipt": { "receiptNr": "432423", "receiptMerchant": "Merchant: Demo Test, Terminal ID: 12425423, Location: Store 123", "receiptCustomer": "Customer Name: John Doe, Date: 2025-02-10, Amount: 5000 EUR", "receiptCopies": 2, "receiptsNumber": 10234 }, "dcc": { "foreignAmount": 1000, "foreignCurrencyCode": "AED", "commission": "123", "margin": "2432", "rateValue": "23423", "source": "some source", "timestamp": "2025-02-27T15:05:06", "disclaimerText": "some text" }, "credentialOnFile": { "type": "UNSCHEDULED", "initialPayment": true, "unscheduled": { … } }, "paymentMethod": { "card": { … }, "directDebit": { … } } }