menu

Payment API

What's on this page

Online Payments / Payment Methods / Terminal

Terminal

Shopper Country Sale Refund Authorise / Capture Void Token Vault Mandates
Selected few ✓ ✓ ✓

Terminal is limited to to countries that have access to CCV Terminals. A CCV Terminal is required.

Introduction

Terminal is a payment method that lets you initiate a transaction on your CCV Terminal through the cloud. This flexible payment solution enables you to create your own custom solution for in-store payments, while still benefiting from the features of our Single API.

Guidelines

  1. Create a payment with the payment method set to terminal and use a webhook or notification.
  2. This wil initiate the payment on the CCV Terminal. The customer can then pay by using the CCV Terminal.
  3. You can redirect the customer to the payUrl to show the progress and status of the payment on the payUrl, or you can wait for the notification to receive updates so you can display them yourself.
  4. When CCV receives the payment confirmation from the CCV Terminal, the payment becomes successful.
  5. If you used a webhook or notification, CCV will inform you about the change. Alternatively, you can also query they payment status on regular intervals.

Method API details

Payment

Request

Terminal needs some additional details to process the payment, such as the terminalId of the CCV Terminal to use for the payment. See Terminal Payment Details for more information about the details fields for Terminal payments.

{
    "amount": 9.99,
    "currency": "eur",
    "method": "terminal",
    "returnUrl": "https://shop/return?order=123456",
    "webhookUrl": "https://shop/payhook?order=123456",
    "merchantOrderReference": "123456",
    "description": "Order 123456",
    "language": "eng",
    "details" : {
        "port" : 6235,
        "managementSystemId" : "000103030",
        "ip" : "127.0.0.1",
        "terminalId" : "1234536",
        "accessProtocol" : "OPI_NL",
        "operatingEnvironment" : "ATTENDED",
        "merchantLanguage" : "NLD",
        "supportPartialApproval" : true,
        "acquirerDiscretionaryData" : "01",
        "cardCircuitCollection" : [ "SODX", "EDRD", "PAYF" ]
      }
}

Response

{
  "amount": 9.99,
  "created": 1776151734603,
  "currency": "eur",
  "description": "Order 123456",
  "details": {
    "operatingEnvironment": "ATTENDED",
    "port": 6235,
    "managementSystemId": "1234567",
    "ip": "188.165.118.154",
    "terminalId": "1234567",
    "wakeUpType": "CLOUD_CONNECT",
    "merchantLanguage": "ita",
    "accessProtocol": "OPI_NL"
  },
  "language": "ita",
  "lastUpdate": 1776151734603,
  "merchantOrderReference": "123456",
  "method": "terminal",
  "payUrl": "https://onlinepayments.ccv.eu/terminal/poll?reference=TL260414072854599CB87E19B.3",
  "reference": "TL260414072854599CB87E19B.3",
  "returnUrl": "https://shop/return?order=123456",
  "status": "pending",
  "type": "sale"
}
Terminal Payment Details

See Terminal Payment Details for more information about the details fields for Terminal payments.

Refunds

When refunding terminal payments, 2 options are possible, as the original payment reference to refund is not required.

  1. A merchant can start a refund payment for method terminal by providing the reference field in the refund request. Then all the details from the original payment are used for the refund. The merchant can optionally provide additional fields in the refund request.
  2. A merchant can start a refund payment for method terminal by at least providing the amount, currency, language, details and method fields in the refund request. No reference to the original payment is required in this case. The refund will be processed as a new terminal payment, but with the type refund. The details field must contain all the required details for a terminal payment, as the details from the original payment are not used in this case.

With an original payment reference

example request for terminal refund with original reference

curl --basic --user apikey: -H "Content-Type: application/json" --data '{
  "reference": "TL260414072854599CB87E19B.4",
  "merchantOrderReference" : "123456"
}' https://api.psp.ccv.eu/api/v1/refund

Without an original payment reference

example request for terminal refund without original reference*

curl --basic --user apikey: -H "Content-Type: application/json" --data '{
  "method": "TERMINAL",
  "currency": "EUR",
  "amount": 100.43,
  "language": "ENG",
  "merchantOrderReference" : "123456",
  "details": {
    "terminalId": "1234567",
    "managementSystemId": "1234567",
    "accessProtocol": "OPI_NL",
    "ip": "192.168.1.154",
    "port": "6235",
    "operatingEnvironment": "ATTENDED",
    "merchantLanguage": "ita"
  },
  "returnUrl" : "https://yourshop.com"
}' https://api.psp.ccv.eu/api/v1/refund