menu

Payment API

What's on this page

Online Payments / Payment Methods / Landingpage

Landing page

Shopper Country Sale Refund Authorise / Capture Void Token Vault Mandates
Worldwide ✓ ✓* ✓** ✗ ✗ ✗
  • * CCV supports refunds on the child payment, not on the landing page payment directly.
  • ** CCV supports captures on the child payment, not on the landing page payment directly.

See Parent-child Relationship for more information on the relationship.

Introduction

Landing page payments allow the customer to choose a payment method from a list of available payment methods using a hosted payment page. The customer can choose their preferred payment method from all your available payment methods, or you can limit them per payment.

Using this method, you do not need to build a checkout page to ask the customer which payment method they prefer. You can simply create a payment with CCV Online Payments and redirect the customer to CCV.

Guidelines

  1. Create a payment with the payment method set to landingpage and use a webhook or notification.
  2. Redirect your customer to the payment url, as indicated by the payUrl field 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. Payment completion depends on the customer’s payment method. For example, iDEAL payments complete within seconds when the customer returns to your shop. Bank transfers however take one or more days to complete.
  5. Once the payment becomes successful, and you used a webhook or notification, CCV will inform you about the change.

Parent-child Relationship

A successful landing page payment always consists of at least 2 transactions:

  1. the initial landing page transaction you created for the customer
  2. the transaction for the customer’s selected payment method

CCV links the transactions in a parent-child relationship where the landing page transaction is the parent and the customer initiated payment the child.

There may be multiple attempts from the customer. The parent only links to the last attempt, regardless of whether it has a successful or failed status.

Relationship in the API

The parent transaction has an exposed reference to the child. The child transaction has an internal reference to the parent. You can only query the child transaction if you know the parent reference.

Example of a parent transaction

  • There is a reference to the child "childReferenceId": "I240318094453237CB87E190.L"
  • Some properties from the child are available on the parent:
    • paidout
    • methodTransactionId
{
    "lastUpdate": 1710755100169,
    "statusFinalDate": 1710755100169,
    "created": 1710755087260,
    "cancelUrl": "https://onlinepayments-accept.ccv.eu/api/v1/cancel?reference=L240318094447255CB87E191.J",
    "childReferenceId": "I240318094453237CB87E190.L",
    "amount": 9.99,
    "status": "success",
    "details": {
        "expirationDuration": "P0Y2M1DT0H0M0.000S",
        "allowCustomerCancel": true
    },
    "methodTransactionId": "0001710491788081",
    "returnUrl": "https://shop/return?order=123456",
    "webhookUrl": "https://shop/payhook?order=123456",
    "merchantOrderReference": "123456",
    "description": "Order 123456",
    "payUrl": "https://onlinepayments-accept.ccv.eu/landingpage/v2/payment.html?reference=L240318094447255CB87E191.J",
    "paidout": "no",
    "reference": "L240318094447255CB87E191.J",
    "method": "landingpage",
    "type": "sale",
    "language": "nld",
    "currency": "eur"
}

Example of the linked child transaction

  • There is no reference to the parent
  • Payment method specific details are not exposed on the parent transaction
{
  "lastUpdate": 1710755099538,
  "statusFinalDate": 1710755099538,
  "methodTransactionId": "0001710491788081",
  "details": {
    "consumerBic": "INGBNL2A",
    "consumerAccountNumber": "NL53INGB0654422370",
    "consumerName": "Hr E G H Küppers en/of MW M.J. Küppers-Veeneman"
  },
  "status": "success",
  "created": 1710755093318,
  "amount": 9.99,
  "returnUrl": "https://onlinepayments.ccv.eu/landingpage/v2/payment.html?reference=L240318094447255CB87E191.J",
  "merchantOrderReference": "123456",
  "description": "Order 123456",
  "payUrl": "https://shop-vpos-test.ccvlab.eu/ideal-v2/internal/payment-page?idealTransactionId=0001710491788081",
  "paidout": "no",
  "reference": "I240318094453237CB87E190.L",
  "method": "ideal",
  "type": "sale",
  "language": "nld",
  "currency": "eur"
}

Method API details

Payment

Request

The landing page has payment method specific details you may provide. All details have a default value that you can override.

Name Required Description Max Length
expirationDuration No The time until payment expiration in ISO 8601 Duration. Default value and absolute maximum is P2M1D. If banktransfer is selected, expiration has a delay. 20
expirationTimestamp No The epoch timestamp when the payment should expire. Default value and absolute maximum is 2 months and 1 day after initial creation. /
mail No A boolean value that indicates to mail the payment instructions for banktransfer payments. Defaults to true. 5
mailReminder No A boolean value that indicates to mail a reminder of the payment instructions. Only applicable when mail is true. Defaults to true. 5
allowCustomerCancel No A boolean value to show the cancel link on the landing page and on the child transaction page in case of bank transfer. When false the landing page and its bank transfer child transaction payment page show a return link instead of a cancel link. A PENDING landing page or their child can always be cancelled by cancel the payment. Defaults to true. 5
preselectedMethod No A [method preselection]/documentation/payment_api/api_reference/method/#method-preselection in order to bypass customer payment method selection on the landing page if possible.
allowedPaymentMethods No A list of [payment methods to be displayed on the landingpage]/documentation/payment_api/api_reference/method/#method-preselection. If a method is available but not present in this list it will not be shown to the customer on the landingpage. /

Example of a limitation on allowed payment methods

{
    "amount": 9.99,
    "currency": "eur",
    "method": "landingpage",
    "returnUrl": "https://shop/return?order=123456",
    "webhookUrl": "https://shop/payhook?order=123456",
    "merchantOrderReference": "123456",
    "description": "Order 123456",
    "language": "eng",
    "details" : {
        "expirationDuration" : "P0Y2M1DT0H0M0.000S",
        "allowedPaymentMethods" : ["ideal", "paypal"]
    }
}

Example of a card payment with vault storage

{
    "amount": 9.99,
    "currency": "eur",
    "method": "landingpage",
    "returnUrl": "https://shop/return?order=123456",
    "webhookUrl": "https://shop/payhook?order=123456",
    "merchantOrderReference": "123456",
    "description": "Order 123456",
    "language": "eng",
    "details" : {
        "expirationDuration" : "P0Y2M1DT0H0M0.000S",
        "preselectedMethod" : "card",
        "storeInVault" : true
    }
}

Response

Name Description
expirationDuration The time until payment expiration in ISO 8601 Duration. Default value and absolute maximum is P2M1D.
mail In case of banktransfer, A boolean value that indicates to mail the payment instructions. Defaults to true.
mailReminder In case of banktransfer, A boolean value that indicates not to mail a reminder of the payment instructions if mail was true. Defaults to true.
vaultAccessToken In case of card with storeInVault, The Vault Access Token result from storing the card in our vault.
maskedPan In case of card with storeInVault, The masked primary account number.
expiryDate In case of card with storeInVault, The expiry date of the card in format MMYY.
scaToken In case of card with storeInVault, Boolean value that indicates if the Vault Access Token is created for an SCA authenticated card. For more information refer to our 3-D Secure 2 compliance guide.
allowCustomerCancel A boolean value to show the cancel link on the landing page and on the child transaction page in case of bank transfer. When false the landing page and its bank transfer child transaction payment page show a return link instead of a cancel link. A PENDING landing page or their child can always be cancelled by cancel the payment. Defaults to true.
preselectedMethod The [method preselected]/documentation/payment_api/api_reference/method/#method-preselection in order to bypass customer payment method selection on the landing page if possible.
allowedPaymentMethods A list of [payment methods to be displayed on the landingpage]/documentation/payment_api/api_reference/method/#method-preselection
brand In case of card with storeInVault, the brand of the card.

Example of the landing page in combination with a bank transfer

{
    "lastUpdate": 1710755100169,
    "statusFinalDate": 1710755100169,
    "created": 1710755087260,
    "cancelUrl": "https://onlinepayments-accept.ccv.eu/api/v1/cancel?reference=L240318094447255CB87E191.J",
    "childReferenceId": "B240318094453237CB87E190.L",
    "amount": 9.99,
    "status": "pending",
    "details": {
        "expirationDuration" : "P0Y2M1DT0H0M0.000S",
        "mail" :  true,
        "mailReminder" : false
    },
    "methodTransactionId": "0001710491788081",
    "returnUrl": "https://shop/return?order=123456",
    "webhookUrl": "https://shop/payhook?order=123456",
    "merchantOrderReference": "123456",
    "description": "Order 123456",
    "payUrl": "https://onlinepayments-accept.ccv.eu/landingpage/v2/payment.html?reference=L240318094447255CB87E191.J",
    "paidout": "no",
    "reference": "L240318094447255CB87E191.J",
    "method": "landingpage",
    "type": "sale",
    "language": "nld",
    "currency": "eur"
}

Example of the landing page in combination with a card payment

CCV can store the card on file using the CCV Vault. To store cards in the vault using a landing page payment, add field details.storeInVault to the payment request.

{
    "lastUpdate": 1710755100169,
    "statusFinalDate": 1710755100169,
    "created": 1710755087260,
    "cancelUrl": "https://onlinepayments-accept.ccv.eu/api/v1/cancel?reference=L240318094447255CB87E191.J",
    "childReferenceId": "B240318094453237CB87E190.L",
    "amount": 9.99,
    "status": "success",
    "details": {
        "expiryDate" : "1228",
        "expirationDuration" : "P0Y2M1DT0H0M0.000S",
        "maskedPan" : "4111XXXXXXXX1111",
        "vaultAccessToken" : "6A35C942569C3CA797928D44",
        "scaToken": false,
        "brand": "visa"
    },
    "methodTransactionId": "0001710491788081",
    "returnUrl": "https://shop/return?order=123456",
    "webhookUrl": "https://shop/payhook?order=123456",
    "merchantOrderReference": "123456",
    "description": "Order 123456",
    "payUrl": "https://onlinepayments-accept.ccv.eu/landingpage/v2/payment.html?reference=L240318094447255CB87E191.J",
    "paidout": "no",
    "reference": "L240318094447255CB87E191.J",
    "method": "landingpage",
    "type": "sale",
    "language": "nld",
    "currency": "eur"
}