menu

Payment API

What's on this page

Online Payments / Payment Features / Merchant And Customer Initiated Payments

Introduction

CCV supports the ability for merchants to initiate payments on behalf of their customers.
This is useful in scenarios where the customer is not present or where the customer has given permission to the merchant to initiate payments on their behalf.

Using the Mandates API is recommended.

Note

The vault can also be used for future payments where the customer is present.

Note

For Bancontact Wallet Initiated Payments (WIP) see Bancontact WIP.

Knowledge Base

  • The Token Vault used by the vault and mandates api is PCI DSS compliant.
  • We only store card details securely in the Vault. We do not store any other personal information.
  • Vault data is expired and erased when the card expires.

Typical Use Cases

  • Merchant initiated payments (MIT) - where the customer is not present.
  • Customer initiated payments (CIT) - where the customer is present, but the card details are stored in the Token Vault.

Storing Card Details as a Mandate

In this scenario the user will enter their card details using a mandate.

Obtaining Mandate id without a financial first transaction

  1. The customer indicates he wants to obtain a mandate.

  2. The merchant obtains a mandate id using the Mandates API.

  3. When the customer submits their card details we will process and store them. We will then redirect the customer to the returnUrl and call the webhookUrl.

  4. Then you can check the status of the Mandate:

    Example request

    curl --basic --user apikey: https://api.psp.ccv.eu/api/v1/mandate/MAN250802142051429CB87E179.R

    Example response

    {
  "mandateId": "MAN250802142051429CB87E179.R",
  "type": "card",
  "externalMandateReference": "MAN250802142051429CB87E179.R",
  "created": 1762427296707,
  "modified": 1762427311336,
  "signed": 1762427311279,
  "status": "active",
  "merchantOrderReference": "d42c17f4-1446-4f53-850e-98641b9da1d7",
  "signUrl": "https://onlinepayments-accept.ccv.eu/card/payment.html?reference=C251106110816691CB87E192.Z",
  "returnUrl": "http://shop-vpos-test.ccvlab.eu/returnmandate?ec=d8710a9d-bf9c-4f3f-908c-5aa0db529dc8",
  "details": {
    "customerAddress": "Walenstraat 65 Bus 1",
    "customerLanguage": "eng",
    "customerZip": "3740",
    "customerFirstName": "Dirk",
    "customerEmail": "psp-demo-shop@ccvlab.eu",
    "customerLastName": "Teur",
    "customerCity": "Hasselt",
    "customerCountry": "BEL"
  }
}

  5. After effect of completing a payment (successfully or not) we will notify you using a webhook or notification. This allows you to perform additional operations in your system like sending an email to your customer.

Obtaining Mandate during financial first transaction

You can also obtain a mandate during a payment eg, when doing a first payment using obtainMandate and by including sequenceInfo. The payment response will contain a mandate id.

Request

curl --request POST \
--url https://api.psp.ccv.eu/api/v1/payment \
--user X: \
--header 'Content-Type: application/json' \
-d '{
  "amount": 123.00,
  "currency": "eur",
  "method": "card",
  "returnUrl": "https://shop/return?order=123456",
  "webhookUrl": "https://shop/payhook?order=123456",
  "merchantOrderReference": "123456",
  "description": "Order 123456",
  "language": "eng",
  "transactionType" : "sale",
  "obtainMandate": "yes"
}'

Response

{
  "reference": "C251106112147294CB87E193.Z",
  "merchantOrderReference": "d3661851-895d-4f5d-9a96-4b3e90bc71f1",
  "amount": 123,
  "type": "sale",
  "status": "success",
  "currency": "eur",
  "language": "nld",
  "method": "card",
  "brand": "visa",
  "entryMode": "ecom",
  "returnUrl": "http://shop-vpos-test.ccvlab.eu/return?ec=efe6ed6b-c08b-48dd-ac8f-e462a341a7a9",
  "methodTransactionId": "czMii2",
  "created": 1762428107305,
  "lastUpdate": 1762428136838,
  "statusFinalDate": 1762428136838,
  "details": {
    "maskedPan": "4242XXXXXXXX4242",
    "cardholderFirstName": "Daniel",
    "cardholderLastName": "Siggurt",
    "authorisedAmount": 123,
    "acquirer": "Valitor",
    "acquirerResponseCode": "00",
    "acquirerResponseCodeDescription": "ApprovedOrCompletedSuccessfully",
    "initialTransactionId": "BwWfL6CeXK8Yu00",
    "mandateId": "MAN251106112147317CB87E193.0"
  }
}

Using a mandate

When you have a mandate id, you can use it to perform a payment without the need for the customer to enter their card details again.

You can start a MIT or CIT payment using a mandate with the following example. This will execute the payment with the data from the saved card details immediately without user interaction.

Request

curl --request POST \
--url https://api.psp.ccv.eu/api/v1/payment \
--user X: \
--header 'Content-Type: application/json' \

-d '{
  "method": "card",
  "amount": "250.00",
  "currency": "eur",
  "language": "nld",
  "returnUrl": "https://shop/return?order=123456",
  "merchantOrderReference": "My Order 123456",
  "mandateId": "MAN241123222509551CB87E198.0"
}'

Response

{
  "status": "success",
  "reference": "C250324145223810CB87E194.Y",
  "method": "card",
  "type": "sale",
  "language": "nld",
  "currency": "eur",
  "lastUpdate": 1742824343856,
  "returnUrl": "https://shop/return?order=123456",
  "merchantOrderReference": "My Order 123456",
  "details": {
    "maskedPan": "4242XXXXXXXX4242",
    "cardholderFirstName": "John",
    "cardholderLastName": "Doe",
    "authorisedAmount": 250,
    "acquirer": "Valitor",
    "acquirerResponseCode": "00",
    "acquirerResponseCodeDescription": "ApprovedOrCompletedSuccessfully",
    "initialTransactionId": "umMHxEiLnTIu300",
    "mandateId": "MAN241123222509551CB87E198.0"
  },
  "cancelUrl": "https://api.psp.ccv.eu/api/v1/cancel?reference=C250324145223810CB87E194.Y",
  "created": 1742824343823,
  "amount": 5.00,
  "brand": "visa",
  "payUrl": "https://onlinepayments.ccv.eu/card/payment.html?reference=C250324145223810CB87E194.Y",
  "methodTransactionId": "9kFB9V"
}

Storing Card Details in the Vault

In this scenario the user will store card details in our Vault.

Obtaining Vault Access Token without a financial first transaction

  1. The customer indicates he wants to store their card details in the Vault.

  2. The merchant initiates a vault transaction using the Vault API.

  3. We will validate the request and send a pending vault transaction as response

  4. In order to have the card data entered you will have to redirect the customer to the payUrl as generated for this transaction.

  5. The customer will be presented with a card form and be requested to fill in their card details.

  6. When the customer submits their card details we will process that Card details and store them in the Vault. We will then redirect the customer to the returnUrl and call the webhookUrl.

  7. Then you can check the status of the transaction and the Vault Access Token:

    Example request

    curl --basic --user apikey: https://api.psp.ccv.eu/api/v1/transaction?reference=V170802142051429CB87E199.2

    Example response

    {
  "merchantOrderReference" : "123456",
  "returnUrl" : "http://shop/return?order=123456",
  "webhookUrl": "https://shop/hook?order=123456",
  "language" : "eng",
  "lastUpdate" : 1450871414476,
  "payUrl" : "https://onlinepayments.ccv.eu/vault/card.html?reference=V170802142051429CB87E199.2",
  "reference" : "V170802142051429CB87E199.2",
  "created" : 1450871254959,
  "method" : "vault",
  "type" : "token",
  "description" : "Enter card details for use in MyService",
  "status" : "success",
  "details" : {
    "dataType" : "card",
    "expirationDuration" : "P0Y2M1DT0H0M0.000S",
    "expirationTimestamp" : 1457871414476,
    "vaultAccessToken" : "5C810B0AD0B1BC0926EBEA53",
    "brand" : "mastercard",
    "maskedPan" : "XXXXXXXXXXXXX4227",
    "initialTransactionId": "ABC23456282"
  }
}

  8. After effect of completing a payment (successfully or not) we will notify you using a webhook or notification. This allows you to perform additional operations in your system like sending an email to your customer.

Obtaining Vault Access Token during a financial first transaction

You can also obtain a vault access token during a payment eg, when doing a first payment using storeInVault.

Request

curl --request POST \
--url https://api.psp.ccv.eu/api/v1/payment \
--user X: \
--header 'Content-Type: application/json' \
-d '{
  "amount": 10.00,
  "currency": "eur",
  "method": "card",
  "returnUrl": "https://shop/return?order=123456",
  "webhookUrl": "https://shop/payhook?order=123456",
  "merchantOrderReference": "123456",
  "description": "Order 123456",
  "language": "eng",
  "transactionType" : "sale",
  "storeInVault": "yes"
}'

Response

{
  "status": "success",
  "description": "Order 123456",
  "reference": "C250324151052457CB87E19D.Y",
  "method": "card",
  "type": "sale",
  "language": "eng",
  "currency": "eur",
  "merchantOrderReference": "123456",
  "lastUpdate": 1742825476594,
  "entryMode": "ecom",
  "returnUrl": "https://shop/return?order=123456",
  "details": {
    "scaToken": true,
    "maskedPan": "4000XXXXXXXX0028",
    "acquirerResponseCode": "00",
    "vaultAccessToken": "VAULT_ACCESS_TOKEN",
    "dataType": "card",
    "expirationTimestamp": 1745417476578,
    "acquirer": "Valitor",
    "cardholderLastName": "dfg",
    "authenticationProtocol": "3DS2",
    "acquirerResponseCodeDescription": "Approved",
    "expiryDate": "1225",
    "cardholderFirstName": "dfg",
    "expirationDuration": "P0Y0M30DT0H0M0.000S",
    "brand": "visa",
    "authenticationStatus": "Y",
    "initialTransactionId": "ABC23456282"
  },
  "cancelUrl": "https://api.psp.ccv.eu/api/v1/cancel?reference=C250324151052457CB87E19D.Y",
  "created": 1742825452464,
  "amount": 10.00,
  "brand": "visa",
  "payUrl": "https://onlinepayments.ccv.eu/card/payment.html?reference=C250324151052457CB87E19D.Y",
  "statusFinalDate": 1742825476594,
  "methodTransactionId": "5m8btX"
}

Using a Vault Access Token

When you have a Vault Access Token, you can use it to perform a payment without the need for the customer to enter their card details again.

Merchant Initiated Payment (MIT)

You can start a MIT payment using a vault access token with the following example. This will execute the payment with the data from the saved card details immediately without user interaction.

Request

curl --request POST \
--url https://api.psp.ccv.eu/api/v1/payment \
--user X: \
--header 'Content-Type: application/json' \

-d '{
  "method": "card",
  "amount": "5.00",
  "currency": "eur",
  "language": "nld",
  "returnUrl": "https://shop/return?order=123456",
  "merchantOrderReference": "My Order 123456",
  "details": {
    "vaultAccessToken": "VAULT_ACCESS_TOKEN",
    "initialTransactionId: "ABC1235671"
  },
  "sequenceInfo": {
    "type": "UNSCHEDULED",
    "mode": "SUBSEQUENT",
    "source": "MIT"
  }
}'

Response

{
  "status": "success",
  "reference": "C250324145223810CB87E194.Y",
  "method": "card",
  "type": "sale",
  "language": "nld",
  "currency": "eur",
  "lastUpdate": 1742824343856,
  "returnUrl": "https://shop/return?order=123456",
  "merchantOrderReference": "My Order 123456",
  "details": {
    "cardholderFirstName": "dfgd",
    "initialTransactionId": "SomeSchemeTrxId22chars",
    "maskedPan": "4000XXXXXXXX0028",
    "cardholderLastName": "dfg"
  },
  "cancelUrl": "https://api.psp.ccv.eu/api/v1/cancel?reference=C250324145223810CB87E194.Y",
  "created": 1742824343823,
  "amount": 5.00,
  "brand": "visa",
  "payUrl": "https://onlinepayments.ccv.eu/card/payment.html?reference=C250324145223810CB87E194.Y",
  "methodTransactionId": "9kFB9V"
}

Customer Initiated Payment (CIT)

You can start a CIT payment using a vault access token with the following example. This will execute the payment with the data from the saved card details after the customer has authenticated themselves using the payUrl. You should redirect the customer to the payUrl to authenticate themselves.

curl --request POST \
--url https://api.psp.ccv.eu/api/v1/payment \
--user X: \
--header 'Content-Type: application/json' \

-d '{
  "method": "card",
  "amount": "5.00",
  "currency": "eur",
  "language": "nld",
  "returnUrl": "https://shop/return?order=123456",
  "merchantOrderReference": "My Order 123456",
  "details": {
    "vaultAccessToken": "VAULT_ACCESS_TOKEN",
    "initialTransactionId: "ABC1235671"
  },
  "sequenceInfo": {
    "type": "UNSCHEDULED",
    "mode": "SUBSEQUENT",
    "source": "CIT"
  }
}'

Response

{
  "status": "pending",
  "reference": "C250324145403912CB87E198.Y",
  "method": "card",
  "type": "sale",
  "language": "nld",
  "currency": "eur",
  "lastUpdate": 1742824443972,
  "returnUrl": "https://shop/return?order=123456",
  "merchantOrderReference": "My Order 123456",
  "details": {
    "cardholderFirstName": "dfgd",
    "initialTransactionId": "SomeSchemeTrxId22chars",
    "maskedPan": "4000XXXXXXXX0028",
    "cardholderLastName": "dfg"
  },
  "cancelUrl": "https://api.psp.ccv.eu/api/v1/cancel?reference=C250324145403912CB87E198.Y",
  "created": 1742824443919,
  "amount": 5.00,
  "brand": "visa",
  "payUrl": "https://onlinepayments.ccv.eu/card/payment.html?reference=C250324145403912CB87E198.Y"
}

FAQ

How do I perform Customer Initiated Payments (CIT)?

The mandate and vault api can be used for recurring payments, however using mandates is recommended.
When you store the card details in the Vault, you can use the resulting mandate id or Vault Access Token for future payments.

You can initiate a payment with the Vault Access Token and the source in sequenceInfo object set to CIT.

{
  "sequenceInfo": {
    "type": "UNSCHEDULED",
    "mode": "SUBSEQUENT",
    "source": "CIT"
  }
}

You can combine the source with the mode to indicate if the payment is a subsequent CIT payment or a recurring CIT payment. Please note that the customer may need to authenticate themselves before the payment can be completed.

How do I perform Merchant Initiated Payments (MIT) recurring or unscheduled payments?

The mandate and vault api can be used for recurring payments, however using mandates is recommended.
When you store the card details in the Vault, you can use resulting mandate id or Vault Access Token for future payments.

Then initiate a payment with the type in sequenceInfo object set to RECURRING or UNSCHEDULED with source MIT.

{
  "sequenceInfo": {
    "type": "RECURRING",
    "mode": "SUBSEQUENT",
    "source": "MIT"
  }
}

What happens if a Subsequent / Recurring transaction fails?

Please contact ecommerce@ccv.eu for more information. We will be able to help you with this. Retrying the MIT transaction will not help in many cases. You should be aware that these transactions are not guaranteed to succeed. Please act accordingly on your system…

When using the vault do I have to store the initial transaction ID myself?

Yes, you have to store the initial transaction ID yourself. You have to pass the initialTransactionId in the sequenceInfo in the payment request when using a vault access token.
If you do not wish to or cannot store this ID using our Mandates API is recommended, which is specifically designed for this use case.

Can I use the Vault for Bancontact Wallet Initiated Payments (WIP)?

Yes you can, keep in mind there is a difference in the api usage when doing the subsequent transaction. See Bancontact WIP for more information.

Can I use the Vault for Apple Pay, Google Pay or any other method than card?

No you cannot. Please use our Mandates API for these and others.

Can I use the Vault in combination with authorise and capture?

Yes you can. You can use the Vault Access Token in the payment request as you would with any other payment. See Authorise and Capture for more information.

What should I do if I want to use the Token Vault? Can I use it by default?

By Default, the Token Vault is not enabled. Please contact ecommerce@ccv.eu to enable the Vault for your account. Together with CCV support, we can validate your use-cases, needs, and requirements. This will allow us to setup the Token Vault correctly and support you on your api integration.