Online Payments / Payment Methods / American Express

Card

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 1 (Only Bancontact): This is the legacy authentication method, which, in case of the card is enrolled, the customer is redirected towards the ACS, an external system from the bank to authenticate themselves. The customer is returned to the CCV Online Payments system before returning to the shop.
• 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, there is a third option: 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.

Redirect customer to CCV Pay for card entry

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"
}

Using a card stored in the 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 card holder 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"
    }
}

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"
    }
}

Embedded card data entry

The basic card payment integration means you redirect the customer to CCV. CCV requests the card data from the card holder 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 card holders device, you send the card data directly from the card holders 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 operations 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.