menu

Payment API

What's on this page

Online Payments / Payment Features / Partial Payment

Partial Payment

For a standard payment the merchant creates a payment, which is used by the customer to pay for an order completely. A single payment amount is covered by the requested or customer-selected payment amount. We can call this a standard payment method. With partial payment it’s possible to use multiple methods together to pay for an order in parts, using a standard payment method and partial payment method Gift. The amount a customer must pay can be divided over multiple transactions. A method such as this is called a partial payment method. Note that a gift method standalone payment can also be requested, where a single gift card is used to (partially) pay for the requested amount.

Business Case

When a customer has a gift card at hand which is

  • supported by CCV
  • the merchant is offering as a payment method
  • is valid and has a (remaining) balance

the customer can use the balance of the gift card to pay for (part of) the amount. The customer is then free to choose an additional method such as card to cover the remaining amount. If the gift card covers the whole amount, the payment amount is subtracted from the gift card balance and the transaction is completed without the need of selecting another method.

Whereas usually the responsibility of displaying the supported card brands falls to the integrating merchant, CCV has taken care of this by using our landingpage to display the brands available, with an image if present, and allow the customer to choose which card brands to use, how many cards, before selecting the final payment method to completely pay for the purchase. The integrating merchant does not have to make adjustments to the webshop or make any further changes as brand subscriptions change or the brands change.

Requirements

  • The customer must have a valid gift card which still has balance.
  • The merchant must be enrolled for said brand of gift card with the gift acquirer (for example CONNECT).
  • The merchant has an active and correctly configured gift config.
  • The merchant gift method config has enabled partial payment.
  • The merchant has enabled method landingpage, which serves as a nexus for payment method selection but also for partial payments.

Gift Card Brands

In order for a customer to know what card is available and can be used, we display the name and a corresponding image (if present). A customer must select a gift card brand before proceeding to claim a gift card.

A merchant who wishes to make use of gift cards must be enrolled for these brands with a gift acquirer supported by CCV. This is then configured and these subscribed brands can then be retrieved via /method. A merchant can thereby also display all supported brands by name and as images on a webshop page, but simply redirect the customer to the landingpage payUrl.

Payout process

Payment method Gift is not a collecting payment method. This means that the amount will not paid out by CCV, but directly from the issuer of the card to the merchant. However, the method selected to cover the remaining amount can be collecting. For example, for a transaction using landingpage when a customer:

  • chooses to pay via creditcard, there is no choice but to pay for the whole amount, and that amount is collected and paid out.
  • chooses to pay via paypal, there is no choice but to pay for the whole amount, and that amount is not collected or paid out as paypal is not a collecting method.
  • chooses to add a gift card with a value equal to or higher than the request amount, the whole amount is covered and none is collected or paid out by CCV, but by the issuer.
  • chooses to add one or more gift cards with a combined value lower than the request amount, and then uses a collecting creditcard brand to pay for the remaining amount, only the remaining amount is collected and paid out.
  • chooses to add one or more gift cards with a combined value lower than the request amount, and then uses iDeal to pay for the remaining amount, only the remaining amount is collected and paid out.

Use Cases

Payment

This example is based on a standard landingpage payment. The customer will use a gift card to pay for the requested amount in part and the remaining amount with a standard iDeal payment.

  1. You initiate a new payment of type landingpage

    {
    "amount": 34.56,
    "currency" : "eur",
    "method" : "landingpage",
    "returnUrl" : "https://shop.merchant.com/return?order=123456",
    "merchantOrderReference" : "123456",
    "description" : "Order 123456",
    "language" : "nld",
    "billingAddress": "Westvoortsedijk",
    "billingCity": "Arnhem",
    "billingState": "GE",
    "billingPostalCode" :"6827 AT",
    "billingCountry": "NL",
    "billingHouseNumber": "55"
}

  2. CCV Pay responds with a generated transaction containing a unique payUrl.

     {
     "language": "nld",
     "method": "landingpage",
     "currency": "eur",
     "billingAddress": "Westvoortsedijk",
     "billingPostalCode": "6827 AT",
     "billingCity": "Arnhem",
     "billingState": "GE",
     "billingCountry": "NL",
     "created": 1610111865939,
     "merchantOrderReference": "123456",
     "lastUpdate": 1610111865939,
     "returnUrl": "https://shop.merchant.com/return?order=123456",
     "reference": "L210108141745898CB87E182.2",
     "billingHouseNumber": "55",
     "cancelUrl": "${baseUrl}/card/cancel/merchant?reference=L210108141745898CB87E182.2",
     "amount": 23.45,
     "payUrl": "${baseUrl}/landingpage/payment.html?reference=L210108141745898CB87E182.2",
     "description": "Order 123456",
     "status": "pending",
     "type": "sale"
 }

  3. You redirect the customer to the payUrl, which results in the landingpage. Here the option to use a gift card is shown. Landingpage with Gift Partial Payment

  4. The customer selects the option to use a gift card to pay for part of or the whole payment amount. The balance will be subtracted after the gift card is validated and its current balance is retrieved. Customer selects Gift Card for Partial Payment

  5. The customer selects the brand of the gift card and enters the code. Depending on the brand, the code might be subjected to format validation. The customer can then submit the code and claim the gift card in order to subtract its remaining balance from the payment amount. Customer selects Gift Card Brand and enters code

  6. The customer can see the gift card balance applied. If the balance of the gift card was equal to or higher than the payment amount, the customer is redirected to the returnUrl as the payment is now completed. However, if the gift card was invalid this will be indicated here, leaving the complete payment amount open. More gift cards can be added to further reduce the remaining payment amount. Customer claims gift card for balance EUR 40

  7. The customer finalises the payment by selecting a payment method for the remaining amount shown. However, if the gift card was invalid this will be indicated here, leaving the complete payment amount open. Customer selected payment method to complete payment

  8. The customer is redirected to the payment form of the selected payment method, where after completion the customer is redirected to the returnUrl.

  9. You can check the status of the payment by Reading the Transaction. If the payments succeeds, the transaction is updated with status success.

    {
  "language": "nld",
  "method": "landingpage",
  "currency": "eur",
  "billingAddress": "Westvoortsedijk",
  "billingPostalCode": "6827 AT",
  "billingCity": "Arnhem",
  "billingState": "GE",
  "billingCountry": "NL",
  "created": 1610111865939,
  "methodTransactionId": "test-e1ebc659-1d60-492c-a8ca-93f79327e4fe",
  "paidout": "no",
  "merchantOrderReference": "123456",
  "lastUpdate": 1610111919539,
  "returnUrl": "https://shop.merchant.com/return?order=123456",
  "reference": "L210108141745898CB87E182.2",
  "billingHouseNumber": "55",
  "entryMode": "ecom",
  "amount": 23.45,
  "description": "Order 123456",
  "status": "success",
  "type": "sale"
}