menu

Payment API

What's on this page

Online Payments / Payment Features / Embedded Card Payments

Embedded Card Payments

CCV provides a number of options to process card payments.

  • A card payment using the card method. This method is used for payments that are processed in the CCV environment. The card details are entered by the customer on the CCV payment page. This is a PCI-compliant solution for merchants that are not PCI compliant themselves.
  • A card payment using the card method and post card data using the cardDataUrl. See the Payment Request API Documentation for more information on how to use this method.
  • A card payment using the card method and providing the card details in the request body. This is a PCI-compliant solution for merchants that are PCI-compliant themselves. See this page for more information on how to use this method.
    • Merchants can either provide the customer 3DS authentication from their own systems or use CCV to facilitate the customer 3DS authentication.

Providing the card details in the request body

By default, CCV does not allow merchants to provide the card details in the request body. This is a PCI-compliant solution for merchants that are PCI compliant themselves. To enable this feature, please contact your account manager.

Please see the Payment Request API Documentation for more information on the request body structure. When providing the card details in the request body, the following fields are required:

  • pan: The card number.
  • expiryDate: The expiry date of the card in the format MMyy or MMyyyy.
  • cardholderFirstName: The first name of the cardholder.
  • cardholderLastName: The last name of the cardholder.

The following fields are optional:

  • cvc: The CVC code of the card. This is the case for Bancontact cards.

Providing 3DS Authentication details un the request body

When providing the card details in the request body, merchants can either provide the performed 3DS authentication details or use CCV to facilitate the customer 3DS authentication. This is useful for merchants that want to use their own solution to facilitate customer 3DS authentication and only use CCV to process the transaction.

When no 3DS authentication details are provided:

  • CCV will automatically facilitate the customer 3DS authentication, unless an exemption is passed or the transaction is flagged as MIT.
  • The merchant will need to redirect the customer to the payUrl in the payment response where the customer can complete the 3DS authentication and complete the payment.

When 3DS authentication details are provided:

  • CCV will complete the transaction using the provided 3DS authentication details. There is no need to redirect the customer to the payUrl.

The following fields are used for 3DS authentication: These fields are optional and can be provided if you want to use your own solution to facilitate customer 3DS authentication. If not provided, CCV will automatically facilitate the customer 3DS authentication.

These fields should be provided within a 3ds2 object in the details object of the request body:

  • authenticationType: The type of authentication used for the transaction as received from the 3DS server.
  • messageVersion: The version of the authentication used for the transaction.
  • dsTransID: The Directory Server Transaction ID of the authentication used for the transaction as received from the 3DS server.
  • transStatus: The status of the authentication used for the transaction.
  • authenticationValue: The authentication value of the cardholder, as received from the 3DS server.
  • eci: The ECI value of the authentication used for the transaction as received from the 3DS server.
  • acsChallengeMandated: Indicates whether a challenge is mandated for the authentication.

Examples

Send Card payment from a PCI compliant environment without 3DS Authentication

Suppose you are already collecting credit card data within your PCI compliant environment and want to process card payments in your shop.

  1. The customer is done shopping and proceeds to checkout

  2. You request their authentication or a new registration

  3. Once the authentication is complete, you present the customer with the possible payment methods.

  4. The customer chooses to pay using the card method

  5. You request their credit card data

  6. You create a new payment using the card method with all card details attached.

    Example request

    curl --basic --user apikey: -H "Content-Type: application/json" --data '{
  "amount": 9.99,
  "currency": "eur",
  "method": "card",
  "brand": "visa",
  "returnUrl": "http://shop/return?order=123456",
  "merchantOrderReference": "123456",
  "description": "Order 123456",
  "language": "eng",
  "details": {
    "pan": "4111111111111111",
    "expiryDate": "1121",
    "cardholderFirstName": "John",
    "cardholderLastName": "Doe",
    "cvc": "123"
  }
}' https://api.psp.ccv.eu/api/v1/payment

    Example response

    {
  "merchantOrderReference": "123456",
  "amount": 9.99,
  "brand": "visa",
  "returnUrl": "http://shop/return?order=123456",
  "language": "eng",
  "lastUpdate": 1450871414476,
  "payUrl": "https://onlinepayments.ccv.eu/card/payment.html?reference=C151223124734945CB87E191.0",
  "reference": "C151223124734945CB87E191.0",
  "created": 1450871254959,
  "currency": "eur",
  "method": "card",
  "type": "sale",
  "description": "Order 123456",
  "status": "pending"
}

  7. In order to have the payment completed, you’ll need to redirect your customer to the pay url (payUrl) as generated for the payment.

    If you choose to not use 3-D secure, e.g. with an exemption, you can skip this step and continue with step 10.

  8. Depending on your merchant configuration and the result of the 3D Secure for the card details, your customer will have to follow several steps to complete the payment.

  9. As a final result, we return the customer back to your shop. This return url (returnUrl) is provided by you when you initiated the request in step 6.

  10. From this point forward, you should follow step 10 and up like when handling a regular shop payment.

Send Card payment from a PCI compliant environment with 3DS Authentication

Suppose you are already collecting credit card data within your PCI compliant environment and authenticate the consumers and want to process card payments in your shop.

  1. The customer is done shopping and proceeds to checkout

  2. You request their authentication or a new registration

  3. Once the authentication is complete, you present the customer with the possible payment methods.

  4. The customer chooses to pay using the card method

  5. You request their credit card data

  6. You request the customer to authenticate the card details using your own 3DS authentication solution.

    You will need to collect the following information from the 3DS server:

    • authenticationType
    • messageVersion
    • dsTransID
    • transStatus
    • authenticationValue
    • eci
    • acsChallengeMandated

  7. You create a new payment using the card method with all card details attached.

    Example request

    curl --basic --user apikey: -H "Content-Type: application/json" --data '{
  "amount": 9.99,
  "currency": "eur",
  "method": "card",
  "brand": "visa",
  "returnUrl": "http://shop/return?order=123456",
  "merchantOrderReference": "123456",
  "description": "Order 123456",
  "language": "eng",
  "details": {
    "pan": "4111111111111111",
    "expiryDate": "1121",
    "cardholderFirstName": "John",
    "cardholderLastName": "Doe",
    "cvc": "123",
    "3ds2" : {
      "authenticationType": "03",
      "messageVersion": "2.2.0",
      "dsTransID": "be05c24c-506e-4056-b085-5c80fff11a81",
      "eci": "02",
      "transStatus": "Y",
      "authenticationValue": "jGd+EtQ3wQy9CBAcNQWIAyYAAAA=",
      "acsChallengeMandated": "true"
    }
  }
}' https://api.psp.ccv.eu/api/v1/payment

    Example response

    {
  "merchantOrderReference": "123456",
  "amount": 9.99,
  "brand": "visa",
  "returnUrl": "http://shop/return?order=123456",
  "language": "eng",
  "lastUpdate": 1450871414476,
  "payUrl": "https://onlinepayments.ccv.eu/card/payment.html?reference=C151223124734945CB87E191.0",
  "reference": "C151223124734945CB87E191.0",
  "created": 1450871254959,
  "currency": "eur",
  "method": "card",
  "type": "sale",
  "description": "Order 123456",
  "status": "success"
}

  8. From this point forward, you should follow step 10 and up like when handling a regular shop payment.

Benefits

  • You can implement your own payment page.