menu

Payment API

What's on this page

Online Payments / Payment Methods / Apple Pay

Apple Pay

Shopper Country Sale Refund Authorise / Capture Void Token Vault Mandates
Worldwide ✓ ✓ ✓

Apple Pay is a payment method that enables customers to pay online through their Apple Pay wallet. The Apple Pay wallet is backed by a credit or debit card. Not all banks support the use of their debit and/or credit cards in the Apple Pay wallet.

Apple Pay is only supported on devices and browsers that support Apple Pay. Apple Pay is supported on iPhone, iPad and macOS via the Safari browser. Since the release of iOS 18 third-party browsers are also supported for Apple Pay, by using an iPhone with iOS18 to scan the Apple Pay popup on other browsers and/or operating systems. More information on the Apple Pay support page

  1. The customer selects the Apple Pay payment method your checkout page. Depending on the integration type, CCV or you present an Apple Pay button the customer can click on.
  2. The Apple Operating system will show a pop-up to the customer, where the customer can change the credit/debit card to be used for this transaction.
  3. The customer will confirm the payment in a secure way as decided by the Apple Pay systems.
    1. On iPhone or iPad with Face ID or Touch ID.
    2. On Apple Watch with a double click on the side button
    3. On a Mac with Touch ID or, when no Touch ID is available, with a bluetooth-connected iPhone or Apple Watch. Make sure that you’re signed in with the same Apple ID on all devices.
  4. After the payment is successful, the result will be shown to the customer by Apple Pay.
  5. The pop-up disappears and the customer will be returned to the merchants post-order page.

See Apple Pay home page for more information on how the Apple Pay ecosystem works.

Integration Guide

Before you begin

  • If you haven’t done so already, make sure to set up your test account and get your API key to start testing. Contact ecommerce@ccv.eu for questions surrounding your test account and credentials. Contact psp-support@ccvlab.eu for technical support.

Note

Keep in mind that your API key must not be exposed to the customer for any reason whatsoever.

Hosted Payment Page Integration

The below steps describe a typical integration through CCV for Apple Pay transactions:

  1. The customer is done shopping and proceeds to checkout.

  2. The webshop presents the customer with the possible payment methods. It is recommended to only show Apple Pay as a possibility when the current browser and/or device supports this. See browser compatibility for more information.

  3. The customer selects payment method Apple Pay.

  4. At this point you want us to handle the payment. Your backend system initiates a payment transaction using the API. See also Create a new payment.

    • Specify a returnUrl to where the customer should be redirected after the payment is completed (successfully or otherwise). This can be a link to your webshop or a deeplink to your mobile application.
    • You can register to our notification system to receive notifications regarding the transaction. Visit our Notifications section for more info.

    Example cURL request

    curl --basic --user apikey: -H "User-Agent: Shop123456" -H "Idempotency-Reference: 1FAvu5eqNFwohXwPZLJajVecN5AIPaUl7qPFi4jFx4Hvt4SeUO" -H "Content-Type: application/json" --data '<INSERT REQUEST BODY HERE>' https://api.psp.ccv.eu/payment

    Request body details

    {
  "amount" : 0.10,
  "currency" : "eur",
  "method" : "applepay",
  "returnUrl" : "http://shop/return?order=123456",
  "merchantOrderReference" : "123456",
  "description" : "Order 123456",
  "language" : "eng"
}

  5. After we validated the input parameters, we’ll return a new payment transaction. See also Payment object.

    Example response

    {
 "created" : 1667212745322,
  "method" : "applepay",
  "language" : "eng",
  "currency" : "eur",
  "lastUpdate" : 1667212745322,
  "returnUrl" : "http://shop/return?order=123456",
  "payUrl" : "https://onlinepayments.ccv.eu/applepay/payment.html?reference=A221031113905285CB87E194.1",
  "reference" : "A221031113905285CB87E194.1",
  "merchantOrderReference" : "123456",
  "amount" : 0.10,
  "paidout" : "no",
  "type" : "sale",
  "description" : "Order 123456",
  "status" : "pending"
}

  6. Redirect your customer to the payUrl as generated for the payment.

    • For details on how to use the payUrl inside a mobile application, visit the payUrl mobile integration consideration section below.
    • Your customer will be shown the Apple Pay Hosted Payment page from CCV, and asked to click the Apple Pay button.

  7. The Apple Operating System will show a pop-up to the customer, where the customer can choose the credit/debit card to be used for this transaction.

  8. The customer will confirm the payment in a secure way. Which way exactly is decided by the Apple Pay systems, it could be:

    1. On iPhone or iPad with Face ID or Touch ID.
    2. On Apple Watch with a double click on the side button
    3. On a Mac with Touch ID or, when no Touch ID is available, with a bluetooth-connected iPhone or Apple Watch.

  9. After the payment is successful, the result will be shown to the customer by Apple Pay.

  10. After this, CCV will redirect the customer back to the returnUrl you provided in the initial payment request, see step 5. Import note: You should not assume that the customer will return! See the returnUrl integration consideration below.

  11. At this point you don’t know whether the payment was successful or not.

  12. You must request the status of the payment to complete your order correctly. See also Payment status.

    Example request

    curl --basic --user apikey: https://api.psp.ccv.eu/transaction?reference=A221031113905285CB87E194.2

    Example response

    {
  "method": "applepay",
  "merchantOrderReference": "123456",
  "lastUpdate": 1632127457400,
  "details": { },
  "paidout": "no",
  "returnUrl": "http://shop/return?order=123456",
  "payUrl" : "https://onlinepayments.ccv.eu/applepay/payment.html?reference=A221031113905285CB87E194.1",
  "amount": 0.10,
  "reference": "A221031113905285CB87E194.2",
  "entryMode": "ecom",
  "created": 1631889346517,
  "currency": "eur",
  "language": "eng",
  "description": "Order 123456",
  "status": "success",
  "type": "sale"
}

  13. Assuming the payment is successful, you can contact the customer by email with a confirmation, show an appropriate notification on the shop, …

  14. As a side effect of completing a payment (successfully or not), we will notify you using either a webhook or notifications. This allows you to perform additional operations in your system like sending an email to your customer.

    Import note: A webhook does not contain any data except our payment reference. You must request the status of the payment before taking actions like shipping the order!

Direct Integration

When the usage of the hosted payment page isn’t desired you can also add the Apple payment method specific details to the payment request. This is only possible if agreed upon during merchant onboarding when you are using your own Apple IDs for Apple Pay.

Name Required Description Max Length
applePayEncryptedToken Yes The entire encrypted token as received by Apple,
including paymentData, paymentMethod and transactionIdentifier as json.		 N/A

Example

{
  "amount" : 0.1,
  "currency" : "EUR",
  "method" : "applepay",
  "returnUrl" : "http://shop/?order=8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "metadata" : "my custom metadata",
  "merchantOrderReference" : "8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "description" : "API Payment description",
  "language" : "eng",
  "details": {
    "applePayEncryptedToken" : {
      "paymentData": {
        "data": "6g1wT+OeD9vZxL2AhI...DATA_REDACTED",
        "signature": "MIAGCSqGSIb3DQEHAqCAMI...DATA_REDACTED",
        "header": {
          "publicKeyHash": "l0xf53V7Xk3bIRZ2aO4xp2j91oQANO7X4oFsUgMdLk8=",
          "ephemeralPublicKey": "MFkwEwYHKo..DATA_REDACTED",
          "transactionId": "bc8e4cdaad75aeaa4baba4c65beaf6cafefc82876f230873509e136c8e53119d"
        },
        "version": "EC_v1"
      },
      "paymentMethod": {
        "displayName": "MasterCard 1471",
        "network": "MasterCard",
        "type": "debit"
      },
      "transactionIdentifier": "BC8E4CDAAD75AEAA4BABA4C65BEAF6CAFEFC82876F230873509E136C8E53119D"
    }
  }
}

Hybrid Integration

With the Hybrid integration you can still use the Apple Pay Certificates and Merchant ID from CCV just like the Hosted Payment Page, but instead of using the CCV Hosted Payment Page to show the Apple Pay button you can use your own checkout page.

Include Apple Pay JS in HTML

In order to show the button on your checkout page, you will need to include the Apple Pay Javascript library to your page, see the Apple developer website

<script src="https://applepay.cdn-apple.com/jsapi/v1/apple-pay-sdk.js"></script>

The button can then be shown by:

<apple-pay-button buttonstyle="black" type="buy" locale="el-GR"></apple-pay-button>

Remark: it is recommended to only show the Apple Pay Button when the browser supports Apple Pay payments, see browser compatability

Create Apple Pay Session

When the customer clicks on the Apple Pay button, you will need to create an Apple Pay Session, see Creating an Apple Pay Session. To this Apple Pay Session, you can attach multiple event handlers for different steps in the payment process. See ApplePaySession

var request = {
  countryCode: 'US',
  currencyCode: 'USD',
  supportedNetworks: ['visa', 'masterCard'],
  merchantCapabilities: ['supports3DS'],
  total: { label: 'Your Merchant Name', amount: '10.00' }
}
var session = new ApplePaySession(3, request);

The following Apple Pay events are absolutely necessary in order to complete an Apple Pay transaction:

  • onvalidatemerchant
  • onpaymentauthorized

Providing Merchant Validation

When the Apple Pay framework shows the payment sheet to the customer, it will also call the callback onvalidatemerchant to get a merchant session. When you have retrieved this merchant session, the method completeMerchantValidation needs to be called on the ApplePaySession.

How do we retrieve this merchant session: When this event handler is called, the event contains a property validationURL This property is necessary to create the merchant session. The other parameter that is needed, is the current window location, as this is validated by Apple Pay.

When receiving the onvalidatemerchant event you should call your own webshop backend, passing the event.validationUrl and the window.location.hostname.

For example:

session.onvalidatemerchant = async event => {
    const paymentInitiateRequest = {
        "validationUrl": event.validationURL,
        "domainName": window.location.hostname
    };

    $.ajax({
        type: "POST",
        url: "https://mybackend.io/applepaySession",
        dataType: "json",
        contentType: "application/json; charset=utf-8",
        headers: {
            "Authorization": "Basic my-authentication-scheme"
        },
        data: JSON.stringify(paymentInitiateRequest),
        success: function (response, status, hxr) {
            json = JSON.parse(response.applePayPaymentSession)
            session.completeMerchantValidation(json);
        },
        error: function (XMLHttpRequest, textStatus, errorThrown) {
            console.error("Error fetching merchant session", errorThrown);
        }
    });
};

From your backend you call the payment endpoint with the following properties filled in:

Name Required Description Max Length
applePayValidationUrl Yes The validationUrl as received by the Apple Pay Javascript library in the onvalidatemerchant callback. N/A
applePayDomainName Yes The domain on which the Apple Pay button has been clicked. e.g: onlinepayments.ccv.eu N/A

Example Request

{
    "type": "sale",
    "amount": "1.99",
    "currency": "eur",
    "method": "applepay",
    "language": "eng",
    "description": "CCV payment: 1.99 EUR",
    "metadata": "5ee3700244005a28b38e347b",
    "details": {
        "applePayValidationUrl": "VALIDATION_URL_HERE" ,
        "applePayDomainName": "YOUR_CHECKOUT_DOMAIN_NAME_HERE"
    }
}

Example Response

{
    "paidout": "no",
    "payUrl": "https://onlinepayments.ccv.eu/applepay/payment.html?reference=A221221144242770CB87E152.1",
    "details": {
        "applePayPaymentSession": "{\"epochTimestamp\":1671630163078,\"expiresAt\":1671633763078,\"merchantSessionIdentifier\":\"SSHFC081E.....DEA51F9419420173\",\"nonce\":\"cd1..91\",\"merchantIdentifier\":\"4AF......9B0D\",\"domainName\":\"https://myShopLocation.io\",\"displayName\":\"My Shop Name\",\"signature\":\"30800609...00000000\",\"operationalAnalyticsIdentifier\":\"FMy Shop Name:4AFD...B0D\",\"retries\":0,\"pspId\":\"412...BA\"}"
    },
    "status": "pending",
    "amount": 1.99,
    "created": 1671630162837,
    "metadata": "5ee3700244005a28b38e347b",
    "cardDataUrl": "https://onlinepayments.ccv.eu/applepay/A221221144242770CB87E152.1/encryptedtoken",
    "cancelUrl": "https://onlinepayments.ccv.eu/applepay/A221221144242770CB87E152.1/cancel",
    "lastUpdate": 1671630162837,
    "description": "CCV payment: 1.99 EUR",
    "reference": "A221221144242770CB87E152.1",
    "currency": "eur",
    "method": "applepay",
    "type": "sale",
    "language": "eng"
}

The property applePayPaymentSession needs to be returned to the Javascript on your checkout page, and sent to completeMerchantValidation method of the ApplePaySession (see example above). The property cardDataUrl contains the URL to which the encrypted Apple Pay token needs to be posted. See further. The property cancelUrl contains the URL to which a cancel request can be sent, in case the customer cancels in the Apple Pay payments screen. See further.

Payment Method and Shipping Method updates

In the ApplePaySession, you can also get feedback when the customer chooses a payment method and/or let the customer choose the delivery address. The details of this are out of scope for this guid. The starting point can be here:

Handling Payment Authorisation

When the customer has authorized the Apple Pay payment with Touch ID, Face ID, or a passcode; t he Apple Pay framework will call the event handler onpaymentauthorized. The event contains a property payment that is of type ApplePayPayment. This ApplePayPayment contains (amongst others) the property token, this is the only data that the PSP needs to finish the payment.

This token needs to be sent to the cardDataUrl that is returned by the payment initiation call to the PSP backend. Just as with the payment initiation call, you first need to send this token to your backend, and then perform a call from your backend to the PSP API.

Finally, the Apple Pay framework expects you to call the completePayment method with parameter status. This results in the correct message shown to the customer.

Remark: Make sure you pass the correct status to the Apple Pay framework. You should only pass success if you are certain that the transaction has been given status SUCCESS by our api. See below on how to handle the call to the cardDataUrl

For example:

session.onpaymentauthorized = event => {
    var dataToBeSent = JSON.stringify({
        "encryptedToken": event.payment.token
    });

    $.ajax({
        type: "POST",
        url: "https://mybackend.io/applepayEncryptedToken",
        contentType: "application/json; charset=utf-8",
        data: dataToBeSent,
        success: function (response, status, hxr) {
            const result = {
                "status": ApplePaySession.STATUS_SUCCESS
            };
            session.completePayment(result);
            alert("Success");
        },
        error: function (XMLHttpRequest, textStatus, errorThrown) {
            console.error("Error during sending of encrypted token", errorThrown);

            const result = {
                "status": ApplePaySession.STATUS_FAILURE
            };
            session.completePayment(result);
            alert("Failed");
        }
    });
};

How to handle the result of the cardDataUrl

In the initial payment response, CCV provides a URL you can send the Apple token to. The card data url, in field cardDataUrl in the response, accepts the exact token as you received from Apple. On your backend, you call the cardDataUrl with the following content:

Example Request

{
  "encryptedToken" : {
    "paymentData": {
      "data": "6g1wT...MA2jCj",
      "signature": "MIAGCSqG...AAAAA==",
      "header": {
        "publicKeyHash": "l0xf5...MdLk8=",
        "ephemeralPublicKey": "MFkwEwYH....qjiBeQ==",
        "transactionId": "bc8e4cdaa123456789aba4c65beaf6caf123456789230873509e136c8e53119d"
      },
      "version": "EC_v1"
    },
    "paymentMethod": {
      "displayName": "MasterCard 1471",
      "network": "MasterCard",
      "type": "debit"
    },
    "transactionIdentifier": "BC8E4CDAAD75A123456789C65BEAF612345678976F230873509E136C8E53119D"
  }
}

CCV responds with a HTTP 200 OK in the token is accepted. This does not mean that the transaction has been finished successfully. We recommend you query the payment status to verify if the payment is authorized successful. The transaction should reach a final state (SUCCESS or FAILED) within a couple of seconds. The corresponding result should be returned to the Javascript on your checkout page, so the correct status can be passed to the Apple Pay framework.

Ending the session

Should the customer press the cancel button on the payment screen, or the customer performs a different action that causes the Apple Pay framework to cancel the transaction, the Apple Pay framework will call the oncancel callback. For consistency of our system, we recommend calling the cancelUrl so the transaction can be set to the correct status in our system.

Integration Considerations

CCV PayUrl Mobile Integration

When performing a redirect towards the payUrl from inside a mobile device, we recommend the use of SFSafariViewController for iOS.

Browser compatibility

Apple recommends that you only show the Apple Pay button, when the customer can actually use Apple Pay on the current device/browser. See information on the Apple developer website.

In order to check this, Apple recommends the following code:

if (window.ApplePaySession) {
   var merchantIdentifier = 'example.com.store';
   var promise = ApplePaySession.canMakePaymentsWithActiveCard(merchantIdentifier);
   promise.then(function (canMakePayments) {
       if (canMakePayments) {
           // Display Apple Pay button here.
       }
   });
}

The needed library for this functionality can imported in your html by the following import

<script src="https://applepay.cdn-apple.com/jsapi/v1/apple-pay-sdk.js"></script>

Apple has a number of marketing guidelines on how you should show the Apple Pay button to the customers, on this developer page, the resources for the Apple Pay logo can be found.

ReturnUrl

The return of a customer to your app or webshop (provided by the returnUrl) is the best case scenario. Many reasons exist for why the customer does not return and some are listed here. It is therefore highly recommended that your business logic does not rely on the customer returning to your app or webshop. The actual transaction status is independent of whether the customer returns or not. You should always verify the status of the actual transaction with CCV to know if the payment succeeded or not. This can be done by using webhooks, notifications on your backend system or by the means of polling the transaction status, see also Read a transaction.

Customer chooses not to return

For Apple Pay, when the customer clicks outside of the Apple Pay pop-up, or presses the cancel button, the Apple Pay systems will cancel the transaction towards CCV. It could be that the customer closes the browser window before CCV has the chance of redirecting the customer back to the webshop.

Test and go live

Using your test API key in combination with our API at https://api.psp.ccv.eu, you can start testing your integration. Our Apple Pay testing environment uses the payment amount field to trigger various test scenarios.

See the testing page

Refunds

Apple Pay payments can be refunded within a limited timeframe, depending on the card network that was used by the customer. Only successful payments can be refunded. Visit our refund endpoint documentation for more info.

Mandates

This section provides Apple Pay-specific documentation on mandates.

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

Creating mandates

Mandate API

Hosted payment page integration steps

  1. Create an Apple Pay mandate containing sequenceInfo to indicate the type of merchant initiated transaction. You can optionally register to our notification system to receive notifications regarding the mandate.

    Example request

     {
   "merchantOrderReference": "123456",
   "type": "applepay",
   "returnUrl": "http://shop/return?order=123456",
   "sequenceInfo": {
     "type": "UNSCHEDULED",
     "source": "MIT"
   },
   "notificationRequests": [
     {
         "eventType": "MandateUpdated",
         "notificationUrl": "https://notifiy.shop/1233455"
     }
   ]
 }

    Example response

    {
  "type": "applepay",
  "merchantOrderReference": "123456",
  "created": 1719302197405,
  "status": "pending",
  "mandateId": "MAN240625075637386CB87E193.0",
  "signUrl": "https://onlinepayments.ccv.eu/applepay/payment.html?reference=AP240625095637388CB87E191.E",
  "details": {},
  "returnUrl": "http://shop/return?order=123456"
}

  2. The response contains a mandateId that identifies the created mandate and a signUrl to complete the validation of the mandate. The mandate can only become active (or usable) after a successful signature is performed by visiting the signUrl.

  3. Redirect the customer to the signUrl where he/she can complete the Apple Pay card check transaction (no funds are deducted from the customer since this is a zero-amount transaction)

    • If you subscribed for mandate status update notifications in the initial mandate create request, you will receive a notification on the specified notificationUrl once the validation Apple Pay transaction is finished (successful or otherwise).
    • In case you did not subscribe to any notifications, manual polling of the mandate status is required to retrieve the final status of the mandate contract. Example response
    {
  "type": "applepay",
  "merchantOrderReference": "123456",
  "created": 1719302197392,
  "status": "active",
  "mandateId": "MAN240625075637386CB87E193.0",
  "modified": 1719304200379,
  "signUrl": "https://onlinepayments.ccv.eu/applepay/payment.html?reference=AP240625095637388CB87E191.E",
  "details": {},
  "returnUrl": "http://shop/return?order=123456",
  "externalMandateReference": "ABC3076490714"
}

  5. Assuming the mandate validation is successful, you can now start using mandateId in conjunction with our payment API to create transactions on behalf of the customer without the need for further customer interaction.

Direct integration steps

Currently not supported with the Mandate API in combination with Apple Pay.

Payment API

The same considerations as described previously regarding a “hosted payment page” versus “direct” integration, also apply here.

Below, you can find an example request and response for creating an Apple Pay mandate using the Payment API in combination with the hosted payment page. If a direct integration is desired, the applePayEncryptedToken can be provided directly in the request details as described here.

Example request (hosted payment page)

{
  "amount" : 0.1,
  "currency" : "EUR",
  "method" : "applepay",
  "language" : "NLD",
  "returnUrl" : "http://shop/?order=8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "obtainMandate" : "yes",
  "sequenceInfo" : {
    "source" : "MIT",
    "type" : "UNSCHEDULED"
  }
}

Example response (hosted payment page)

{
  "reference": "A240709163407722CB87E2EF.E",
  "method": "applepay",
  "type": "sale",
  "language": "nld",
  "currency": "eur",
  "lastUpdate": 1720535647724,
  "created": 1720535647724,
  "status": "pending",
  "amount": 0.1,
  "returnUrl": "http://shop/?order=8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "payUrl": "http://localhost:8098/vpos/applepay/payment.html?reference=A240709163407722CB87E2EF.E",
  "paidout": "no",
  "details": {
    "mandateId": "MAN240709143407731CB87E19D.0"
  }
}

Note

Unlike with the Mandate API, other integration options such as “direct” integration, can be used to create Apple Pay mandates using the Payment API.

Performing payments using mandates

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