menu

Payment API

What's on this page

Online Payments / Payment Features / Merchant 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.

This is done by a feature called a Token Vault. The Vault allows you to store card details securely and use them for future payments.

Note

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

Note

We have a brand new API for doing MIT transactions. See our Mandates API for more information.

Note

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

Knowledge Base

  • The Token Vault is PCI DSS compliant.
  • We only store card details securely in the Vault. We do not store any other personal information.
  • When doing a transaction with a vault access token, it is necessary to provide the sequence info in the payment request to indicate what is the nature of the payment.
    • Is the customer present or not.
    • Is the payment a recurring payment or an unscheduled payment.
  • It is required to include the initialTransactionId in the sequenceInfo in the payment request when using a vault access token.
  • By default, a Vault Access Token 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 in the Vault

In this scenario the user will enter their card details via the Vault.

Obtaining Vault Access Token with just an enrollment, 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 API.

    Example request

    curl --basic --user apikey: -H "Content-Type: application/json" --data '{
    "dataType": "card",
    "returnUrl": "http://shop/return?order=123456",
    "language": "eng",
    "description": "Enter card details for use in MyService",
    "merchantOrderReference": "123456",
    "returnUrl": "https://shop/return?order=123456",
    "webhookUrl": "https://shop/hook?order=123456"
}' https://api.psp.ccv.eu/api/v1/vault/initiate

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

    {
  "merchantOrderReference" : "123456",
  "returnUrl" : "https://shop/return?order=123456",
  "webhookUrl": "https://shop/hook?order=123456",
  "language" : "eng",
  "lastUpdate" : 1450871254946,
  "payUrl" : "https://onlinepayments.ccv.eu/vault/card.html?reference=C151223124734945CB87E191.0",
  "reference" : "V170802142051429CB87E199.2",
  "created" : 1450871254946,
  "method" : "vault",
  "type" : "token",
  "description": "Enter card details for use in MyService",
  "status" : "pending"
}

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

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

Can I use the Vault for Customer Initiated Payments (CIT)?

Yes, you can use the Vault for Customer Initiated Payments. When you store the card details in the Vault, you can use the 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"
  }
}

Tou 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 possibly needs to authenticate themselves before the payment can be completed.

Can I use the Vault for Merchant Initiated Payments (MIT)?

Yes, you can use the Vault for Merchant Initiated Payments. When you store the card details in the Vault, you can use the Vault Access Token for future payments.

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

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

Tou can combine the source with the mode to indicate if the payment is a subsequent MIT payment or a recurring MIT payment. No authentication is needed for MIT payments.

Can I use the Vault for recurring payments?

Yes, you can use the Vault for recurring payments. When you store the card details in the Vault, you can use the Vault Access Token for future payments.

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

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

Can I use the Vault for unscheduled payments?

Yes, you can use the Vault for unscheduled payments. When you store the card details in the Vault, you can use the Vault Access Token for future payments.

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

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

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.

What if i do not want to store it myself?

You could check out our Mandates API. This API 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?

No you cannot. Please use our Mandates API.

Can I use the Vault for Google Pay?

No you cannot. Please use our Mandates API.

Can I use the Vault for other methods than card?

No you cannot. Please use our Mandates API for 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 happens if a Subsequent / Recurring transaction fails?

Please contact CCV support 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…

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 CCV support 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.