menu

Payment API

What's on this page

General / Authentication

Authentication

As a merchant you’ll access the system as a remote service without interaction of the customer. The access is restricted and requires you to authenticate.

API Keys

Authentication is performed using API Keys and HTTP Basic Authentication which requires you to send an HTTP Authorization header for each request. The format of the value of the header is defined as the Base64 encoded value of username:password. The username is the value of the API key and the password remains empty.

An example of an API key: t_e40a9b36f4c1fa31f512c623bb5a315696e98cea: results in HTTP Header Authorization: Basic dF9lNDBhOWIzNmY0YzFmYTMxZjUxMmM2MjNiYjVhMzE1Njk2ZTk4Y2VhOg==

Info

This API key is not valid and cannot be used to perform tests with. You must use the keys we provide you.

Operating Mode

The mode defines what will happen with the payment when it is processed by CCV. There are 2 operating modes: LIVE & TEST. To identify the operating mode of a key, use the prefix: l_ for LIVE and t_ for TEST.

Depending on the operating mode of the API key, the payment methods will be processed differently.

When using a TEST key:

  1. A card payment will be handled by a simulated acquirer
  2. An iDEAL payment will be handled by a simulated acquirer
  3. A PayPal payment will be handled by the PayPal sandbox servers
  4. A token will be a simulated token that is NOT PCI compliant
  5. A SoftPOS payment will be handled by a simulator. The CCV SoftPOS app can not be used.

When using a LIVE key:

  1. Your payments will be be processed by an acquirer
  2. You will receive money from your customers using sales or captures
  3. You can send money to your customers using refunds or credits

Note

An API Key is usable for one environment.
Your API Key for the production environment will be different than the your API Key for the test environment.

Entry Mode

The entry mode specifies the environment used to initiate payment. There are 2 entry modes: ECOM & INSTORE.

  1. Online or e-commerce transactions ( ECOM ) take place in a web, online or mobile environment. The software runs on a device owned by the customer; their smartphone, laptop, computer, etc.

  2. In-store ( INSTORE ) transactions take place in a store/merchant environment. The software runs on a merchant-owned device; a kiosk, vending machine, register etc.

Expiration

CCV can set an expiry date on API keys, we don’t do this by default. This is mainly used for security reasons.

The expiration date of an API key is indicated in the response by the HTTP header X-ApiKey-Expiration-Timestamp. It is formatted as a Unix timestamp in milliseconds. Once the expiration date has passed, the key will no longer be valid. All API requests will fail with HTTP status code 401.

The following example shows an expiration at 1711922400000 or 2024-04-01T00:00:00+02:00:

curl -v https://api.psp.ccv.eu/api/v1/method --user t_e40a9b36f4c1fa31f512c623bb5a315696e98cea:
...
>
< HTTP/2 200
< date: Mon, 04 Mar 2024 10:12:10 GMT
< content-type: application/json;charset=UTF-8
< content-length: 1623
< x-apikey-expiration-timestamp: 1711922400000
<
* Connection #0 to host api-accept.psp.ccv.eu left intact
...