Online Payments / Payment Methods / Mastercard

Mastercard

CCV Online Payments supports multiple brands. All brands can be used in the same way.

Acquirers

Payments processed using the card method can be handled by different acquirers in the background. Dependent on your contract, Card payments are processed by Elavon, Valitor, American Express or Bancontact.

Guidelines

The standard card payment flow follows the following steps:

1. Create a payment with the payment method set to card and use a webhook or notification.
2. Redirect your customer to the payment url, field payUrl in the payment response.
3. Once the customer completes the payment, they are redirected to the return url defined in the payment request field returnUrl.
4. When CCV receives the payment confirmation from the acquirer, 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.

Cardholder authentication

Cardholder authentication is transparent for you. It is done after the customer enters their details on the CCV hosted payment page.

There are 2 distinct methods of authentication:

• 3-D Secure Version 2: This is the latest authentication method, which allows for many different modern methods for authentication. See 3DS2 Overview for more information.
• For Bancontact payments Bancontact QR / App payments. See the Bancontact guide for more information.

Method API details

Payment

The use case defines which additional parameters you can provide for card payments.

Flow: Hosted Payment Page

The easiest way to integrate card payments is to define the payment method card in the payment request and redirect the customer to CCV. CCV will handle the authentication if necessary and redirect the customer back to you.

Since the introduction of Strong Customer Authentication (SCA), additional customer information can be added to the request and is highly recommended. See more information on the dedicated SCA documentation

Example

{
    "amount": 9.99,
    "currency": "eur",
    "method": "card",
    "returnUrl": "https://shop/return?order=123456",
    "webhookUrl": "https://shop/payhook?order=123456",
    "merchantOrderReference": "123456",
    "description": "Order 123456",
    "language": "eng"
}

Brand detection

You can provide the customers card brand upfront in the payment request in the field brand. If you do not provide a brand, the CCV Hosted Payment Page will do brand detection.

The available values are

An example looks like

{
    "amount": 9.99,
    "currency": "eur",
    "method": "card",
    "brand": "amex",
    "returnUrl": "https://shop/return?order=123456",
    "webhookUrl": "https://shop/payhook?order=123456",
    "merchantOrderReference": "123456",
    "description": "Order 123456",
    "language": "eng"
}

Flow: Card data from Vault

CCV provides a secure vault to store sensitive information like card data. The reference to a card in the vault is called a vault access token. You can provide a token in the payment request so the cardholder does not need to enter their card details again.

Example

{
    "amount": 9.99,
    "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",
    "details": {
        "vaultAccessToken": "1GV13YEY8ZKCH8ZBJCEOJKDI"
    }
}

Flow: Card data in the payment request

This means you capture the card data on your system before you send it to CCV. The customer does not enter their card data on a CCV Hosted Payment Page. If you don’t want to handle card data on your own, this scenario is not suited for you.

Example

{
    "amount": 9.99,
    "currency": "eur",
    "method": "card",
    "returnUrl": "https://shop/return?order=123456",
    "webhookUrl": "https://shop/payhook?order=123456",
    "merchantOrderReference": "123456",
    "description": "Order 123456",
    "language": "eng",
    "details": {
        "pan": "67032222222222227",
        "expiryDate": "1225",
        "cardholderFirstName": "John",
        "cardholderLastName": "Doe",
        "3ds2": {
          "messageVersion": "2.2.0",
          "authenticationType": "03",
          "dsTransID": "d7c1ee99-9478-44a6-b1f2-391e29c6b340",
          "eci": "05",
          "transStatus": "Y",
          "authenticationValue": "jGd+EtQ3wQy9CBAcNQWIAyYAAAA=",
          "acsChallengeMandated": "true"
          }
    }
}

Flow: Embedded card data

The basic card payment integration means you redirect the customer to CCV. CCV requests the card data from the cardholder in order to complete the payment. If your integration requires a more seamless integration with CCV, you can choose to create an embedded or native card data entry form for your customer. Once the card data is captured on the cardholders device, you send the card data directly from the cardholders device to CCV.

The basic flow:

1. Create a payment with the payment method set to card and use a webhook or notification.
2. Present your customer a card data entry form to capture the card data on their device (mobile native, browser, …)
3. Once the customer entered their card data, send a request to the CCV card data URL as returned in the payment response in the field cardDataUrl
4. Redirect the customer to the CCV payUrl as received in the payment response. There is a possibility customer authentication is required. CCV does not support out of bounds authentication.
5. Once the customer completes the payment, they are redirected to the return url defined in the payment request field returnUrl.
6. When CCV receives the payment confirmation from the acquirer, the payment becomes successful.
7. 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.

Card Data URL API

Resource: cardDataUrl e.g. https://onlinepayments.ccv.eu/card/carddata/embedded?reference=

• Method: POST
• Content-Type: application/json
• Authentication: None
• Parameters

Example

{
  "pan": "67032222222222227",
  "expiryDate": "1220",
  "cvc": "1224",
  "cardholderFirstName": "testName",
  "cardholderLastName": "testLastName"
}

Card data response

• Status Code: 200

PCI Compliance

PCI compliance may be required:

• If the card data is provided directly by the customer to the PSP, No PCI compliance is required. E.g.: Mobile app or browser uses the cardDataUrl to submit the card data directly to CCV.
• If the card data passes through your backend system, PCI compliance is always required. E.g.: Mobile app or browser submits card data to your backend system which in turn uses the cardDataUrl to submit the data to the PSP.

Refund

Card does not require method specific input.

{
  "reference": "P240226130441921CB87E195.Y",
  "description": "Refund of Order 123456"
}

Capture

Card does not require method specific input.

{
  "reference": "P240226130441921CB87E195.Y",
  "description": "Refund of Order 123456"
}

Void

Card does not require method specific input. The operation is only supported for authorisations, i.e. the payments have transaction type authorise.

{
  "reference": "P240226130441921CB87E195.Y",
  "description": "Refund of Order 123456"
}

Mandates

This section provides Card-specific documentation on mandates.

Please refer to Mandates for more context regarding the following sections.

Creating mandates

Payment API

Below, you can find an example request and response for creating a Card mandate using the Payment API.

Example request

{
    "amount": 0.1,
    "currency": "EUR",
    "method": "card",
    "language": "nld",
    "returnUrl": "https://foo.bar",
    "obtainMandate": "yes",
    "sequenceInfo": {
     "type": "unscheduled",
     "source": "mit"
    }
}

Example response

{
    "reference": "C241119154652322CB87E194.B",
    "method": "card",
    "type": "sale",
    "language": "nld",
    "currency": "eur",
    "amount": 0.1,
    "details": {
     "qrCode": "http://localhost:8501/authenticate.html?secureTransferId=fe7bb689-340b-4f56-b898-b5a880c574f3&trm=50",
     "mandateId": "MAN241119144652349CB87E190.0",
     "urlIntent": "http://localhost:8501/authenticate.html?secureTransferId=fe7bb689-340b-4f56-b898-b5a880c574f3&trm=51"
    },
    "returnUrl": "https://foo.bar",
    "payUrl": "http://localhost:8098/vpos/card/payment.html?reference=C241119154652322CB87E194.B",
    "status": "pending",
    "cancelUrl": "http://localhost:8098/vpos/card/cancel/merchant?reference=C241119154652322CB87E194.B",
    "created": 1732027612327,
    "lastUpdate": 1732027612327
}

Performing payments using mandates

The steps required for performing payments using mandates are the same regardless of the used payment method.

Click to Pay

Click to Pay offers a familiar and consistent payment experience for consumers across all card schemes. It is built upon EMV® Secure Remote Commerce (SRC). The Click to Pay logo identifies the merchant’s integration with Click to Pay, providing the consumer with an easy and secure payment experience.

Supported Schemes

The CCV PSP offers Click to Pay for Visa and Mastercard.

Click to Pay is Visa’s solution for e-commerce payments based on the EMV® Secure Remote Commerce (SRC) standards and specifications. It helps enable frictionless online checkout using a single payment profile across a variety of consumer devices and participating online merchants.

Developed by Mastercard and built upon global payment industry standards, Click to Pay delivers an enhanced online checkout experience with the security, convenience, and control consumers enjoy in the physical world. Easy integration makes it simple to offer features that keep consumers happy — now and in the future.

CCV PSP Integration

The use of Click to Pay within the CCV PSP requires minimal integration changes. From a consumer’s point of view, the payment flow provides more options to complete the payment, with or without Click to Pay.

Recommended data in payment request

If you want to provide the best Click to Pay experience to your consumers, provide the following data points in the payment request:

• consumer email address
• consumer phone number

Consumer email address

• Usage:
  • Load cards: When the consumer loads the payment page, Click to Pay uses the email address to query the linked cards. If no cards are found, Click to Pay allows the consumer to provide a different email address.
  • Link card: When the consumer wants to add a new card to Click to Pay, they must provide an email address. This is pre-filled if available in the payment request.
• Payment Request fields: billingEmail or shippingEmail

Consumer phone number

• Usage:
  • Link card: When the consumer wants to add a new card to Click to Pay, they must provide a phone number. This is pre-filled if available in the payment request.
• Payment Request: fields (billingPhoneCountry and billingPhoneNumber) or (shippingPhoneCountry and shippingPhoneNumber)

What if the data is not provided?

• If the consumer uses the same device as in a previous payment and selects “Remember me” during the previous payment, device identification will be used to identify the consumer and load the payment cards.
• If that does not work, the consumer has the ability to provide an alternative email address to look up their registered Click to Pay cards.
• If the consumer does not wish to use Click to Pay, a classic manual card payment remains possible.

User Experience

Consumer without Click to Pay cards

If a consumer has no Click to Pay cards, they can enter a card manually and link it to Click to Pay. In subsequent payments, the consumer will be able to use the card for Click to Pay payments.

Consumer with Click to Pay cards

If a consumer has Click to Pay cards linked, and the device can be identified, the payment form offers a list of the linked cards. In case the device can’t be identified, Click to Pay will request consumer identification using a One Time Password (OTP). The OTP is sent by email or SMS.

Limitations

Issuer Enrollment

Issuers need to enroll consumer cards for Click to Pay. Without this, consumers will not be able to use their cards for Click to Pay.

Acquirer Limitation

To use Click to Pay within the CCV PSP, you must process card transactions through ValitorPay.

Enabled for all schemes

Click to Pay is a global feature: if you have it for Visa, it will automatically be enabled for Mastercard if payment method Mastercard is enabled on your account. And vice versa.