Apple Pay Integration

You can integrate with Apple Pay to process payments on your website.

To use Apple Pay on your website, take note of the following:

You must comply with the Apple Pay guidelines, Apple Pay Identity Guidelines, and Apple Pay on the Web Human Interface Guidelines.
Your domains that will host the Apple Pay button must be served over HTTPS. Review the Apple Pay Server Settings.
Your domains must have a valid SSL certificate.
Your domains that will host the Apple Pay button must be registered with Apple before Apple Pay is enabled.
Review Apple’s Developer Documentation for Apple Pay to see the full set of requirements and best practices.

Set Up Apple Pay on Your Website

Register the domains and subdomains that will display the Apple Pay button for payments with Converge. Registration is done manually through the Converge Support Portal.
Create two files with the name of ‘apple-developer-merchantid-domain-association’ under a folder named ‘.well-known’ in your domain. One of the files should have the .txt extension and the other one should have no extension. An example for the file with the .txt extension is https://yourdomain/.well-known/apple-developer-merchantid-domain-association.txt
Host the demo and production validation files to your server by doing the following:
1. Go to the validation file path. The following are the paths for the demo and production validation files:
  - Demo validation file: https://demo.convergepay.com/.well-known/apple-developer-merchantid-domain-association.txt
  - Production validation file: https://api.convergepay.com/.well-known/apple-developer-merchantid-domain-association.txt
2. Highlight and copy the entire content of the validation file and paste it to the two files (with and without .txt extension) created under the ‘.well-known’ folder.
Obtain the basic auth Converge API endpoint credentials. For more information, see the Authentication section of the Converge API Reference.
From your website within the onvalidatemerchant Apple Pay JS event handler, call the Converge API endpoint to obtain an Apple Pay payment session. For examples, see the example API calls section for this step. And for more information, see Apple Pay's documentation on onvalidatemerchant.
Once the Apple Payment session is obtained, send it as an argument in the Apple Pay completeMerchantValidation function. For more information, see Apple Pay's documentation on completeMerchantValidation.
Apple will call the onpaymentauthorized event handler with the Apple Pay token as an event argument. For more information, see Apple Pay's documentation on onpaymentauthorized.
Within onpaymentauthorized, the Apple Pay token should be passed in a call to the Converge API endpoint to create an Apple Pay payment resource. The Converge API endpoint will respond with an Apple Pay payment. For examples, see the example API calls section for this step.
Use the ID of the returned Apple Pay payment from the previous step in a call to create a transaction for processing. For examples, see the example API calls section for this step.

Enable Apple Pay from the Back Office UI

You can enable Apple Pay from the Payments Settings page. This allows customers to use Apple Pay payments for their transactions. To do this, simply select the Apple Pay check box. By enabling Apple Pay, you agree that you have read and consented to the Apple Pay Web Merchant Terms and Conditions.

Example API Calls for Step 5

Request Body

POST https://uat.api.converge.eu.elavonaws.com/apple-pay-payment-sessions
{
    "account":"7btv9vr8cq3nq8r7p4wjmjkk58bt",
    "initiativeContext":"<your registered domain>"
}

Response Body

{
    "merchant": "https://uat.api.converge.eu.elavonaws.com/merchants/7btv9vr8cq3nq8r7p4wjmjkk58bt",
    "account": "https://uat.api.converge.eu.elavonaws.com/accounts/7btv9vr8cq3nq8r7p4wjmjkk58bt",
    "displayName": "<your DBA name>",
    "initiativeContext": "<your registered domain>",
    "paymentSession": "<the Apple Pay payment session>"
}

Example API Calls for Step 8

Request Body

POST https://uat.api.converge.eu.elavonaws.com/apple-pay-payments
{
    "token": "<the Apple Pay payment session>",
    "card": {
        "billTo": {
            "company": "US_ElavonBank",
            "primaryPhone": "4041234567",
            "alternatePhone": "8885555555",
            "fax": "123456789",
            "email": "email@domain.com",
            "street1": "123 Main Street",
            "street2": "SW",
            "city": "New York",
            "region": "NA",
            "postalCode": "",
            "countryCode": "USA"
        }
    },
    "customReference": "customReference",
    "customFields": {"name1":"value1", "name2":"value2"}
}

Response Body

{
    "href": "https://uat.api.converge.eu.elavonaws.com/apple-pay-payments/8jmkgdx63t77xqtwq6j2f27cykrd",
    "id": "8jmkgdx63t77xqtwq6j2f27cykrd",
    "createdAt": "2022-11-22T06:08:49.949Z",
    "expiresAt": "2022-11-22T06:38:49.000Z",
    "merchant": "https://uat.api.converge.eu.elavonaws.com/merchants/7btv9vr8cq3nq8r7p4wjmjkk58bt",
    "processorAccount": "https://uat.api.converge.eu.elavonaws.com/processor-accounts/kjgfcr2r9y2r2krhbrb36w28tp77",
    "card": {
        "holderName": null,
        "panFingerprint": "prtt98jgc4d7jj2jygvbpfbb4k8nd",
        "expirationMonth": 9,
        "expirationYear": 2026,
        "billTo": {
            "fullName": "John Q Public",
            "company": null,
            "street1": "24 James St",
            "street2": null,
            "city": "Skowhegan",
            "region": New York,
            "postalCode": "04976",
            "countryCode": "USA",
            "primaryPhone": 4045555555,
            "alternatePhone": null,
            "fax": null,
            "email": null
        },
        "maskedNumber": "XXXXXXXXXXX3333",
        "last4": "3333",
        "bin": "370295",
        "scheme": "American Express",
        "brand": "American Express",
        "fundingSource": "unknown",
        "issuingBank": null,
        "issuingCountry": null,
        "issuingCurrency": "EUR",
        "isDebit": "false",
        "isCorporate": "unknown",
        "isDccAllowed": "false"
    },
    "customReference": null,
    "customFields": null,
    "verificationResults": {
        "name": "unprovided",
        "securityCode": "unprovided",
        "addressStreet": "unprovided",
        "addressPostalCode": "unprovided",
        "threeDSecureV1": "unprovided",
        "threeDSecureV2": "unprovided",
        "cryptogramSecurity": "provided"
    }
}

Example API Calls for Step 9

Request Body

POST https://uat.api.converge.eu.elavonaws.com/transactions
{
    "applePayPaymentId": "8jmkgdx63t77xqtwq6j2f27cykrd",
}

Response Body

{
    "id": "79t3cg44993qm8ftb8769c37w8kg",
    "failures": [],
    "doSendReceipt": true,
    "doCapture": true,
    "total": {
        "amount": "20.00",
        "currencyCode": "USD"
    },
    "card": {
        "expirationMonth": 9,
        "expirationYear": 2026,
        "billTo": {
            "street1": "24 James St",
            "city": "Skowhegan",
            "region": New York,
            "postalCode": "04976",
            "countryCode": "USA",
        },
        "last4": "3333",
        "brand": "American Express",
        "scheme": "American Express"
    },
    "createdAt": "2022-11-22T06:08:50.603Z",
    "paymentSession": "https://uat.api.converge.eu.elavonaws.com/payment-sessions/dhpfq6p99tb3m8gxmdjwcwttkt74",
    "source": ""
}