Apple Pay

About Apple Pay

Our Payments API allows your mobile app and online store to accept payments using Apple Watch, iPhone, iPad, or Safari.

Getting started

If this is your first time implementing our APIs we recommend reviewing our Reference guide , to get familiar with Worldline's Payment APIs.

You can find more about Worldline and Apple Pay on Github .

Requirements

Before you accept Apple Pay with Worldline, you need to register a Merchant ID and download a Merchant Certificate (P12) with Apple.

To enable Apple Pay on your Merchant Account, you'll set a password for your P12 using Keychain Access.

1. Under the Category menu, select Certificates .

2. Find and right-click your Merchant ID certificate. Select Export .

3. Ensure your File Format is set to .Personal Information Exchange (.p12) before clicking Save .

4. Enter the password you'll use when uploading your .p12 to the Member Area and click OK .

To turn on Apple Pay for your account, log into the Member Area . Under configuration , click on mobile payments . From the Mobile Payments screen, you can enable Apple Pay by adding your Apple Pay signing certificate.

Click ADD NEW MERCHANT ID , and you'll be able to add your Apple Merchant ID , your P12 File Password , and upload your P12 certificate file.

After you've added your Apple Pay certificate to your account, you can start integrating to your app.

Accepting Apple Pay on iOS

All of the directions and code samples to enable Apple Pay in your iOS app are available through Apple's documentation.

Getting Started with Apple Pay will cover how to use Apple Pay and best practices, Apple Pay Guide has explanations of the user flow and working with Apple Pay, and Apple Pay Sandbox Testing will show you how to test Apple Pay transactions.

API Requests

 curl https://api.na.bambora.com/v1/payments \
    -H "Authorization: Passcode XXX1XXx11Xxx1xX1XxxxXxXXXXx1XXX1XxX1XXXxXXXxXxxxX11XXXxX1" \
    -H "Content-Type: application/json" \
    -d '{
          "amount": 1.00,
          "payment_method": "apple_pay",
          "apple_pay": {
            "passthrough": false,
            "apple_pay_merchant_id": "<your_apple_pay_merchant_id>",
            "payment_token": "<apple_pay_base64_encoded_token>",
            "complete": true
          }
        }'

Apple Pay external decryption*

With Apple Pay External Decryption (passthrough), the decryption is performed by the merchant prior to making the request.

The major differences between a passthrough transaction request and a regular Apple Pay transaction request are that the "passthrough" field must be included and set to true, the "apple_pay_merchant_id" field can be omitted, and the payment token must be decrypted before being base64-encoded and passed. Other than that, a passthrough request will function the same as a regular Apple Pay request, formatting the data in JSON and calling https://api.na.bambora.com/v1/payments/.

curl https://api.na.bambora.com/v1/payments \
    -H "Authorization: Passcode XXX1XXx11Xxx1xX1XxxxXxXXXXx1XXX1XxX1XXXxXXXxXxxxX11XXXxX1" \
    -H "Content-Type: application/json" \
    -d '{
          "amount": 1.00,
          "payment_method": "apple_pay",
          "apple_pay": {
            "passthrough": true,
            "payment_token": "<base64_encoded_decrypted_apple_pay_token>",
            "complete": true
          }
        }'

For merchants not using external decryption, the passthrough parameter is optional, and omitting it will have the same effect as passing it as false. No changes are required for existing integrations using Worldline decryption for Apple Pay.

*TD Support Only

Additional examples

The sample below shows the action taken by a payment button using Swift, generating a payment request.

func paymentButtonAction() {
    // Create a payment request
    let request = PKPaymentRequest()

    request.merchantIdentifier = "merchant.com.mycompany.myapp"
    request.supportedNetworks = [.visa, .masterCard, .amex]
    request.merchantCapabilities = .capability3DS

    // Use a currency set to match your Merchant Account
    request.countryCode = "CA" // "US"
    request.currencyCode = "CAD" // "USD"

    request.paymentSummaryItems = [
        PKPaymentSummaryItem(label: "1 Golden Egg", amount: NSDecimalNumber(string: "1.00"), type: .final),
        PKPaymentSummaryItem(label: "Shipping", amount: NSDecimalNumber(string: "0.05"), type: .final),
        PKPaymentSummaryItem(label: "GST Tax", amount: NSDecimalNumber(string: "0.07"), type: .final),
        PKPaymentSummaryItem(label: "Total", amount: NSDecimalNumber(string: "1.12"), type: .final)
    ]

    self.paymentAmount = NSDecimalNumber(string: "1.12")

    let authVC = PKPaymentAuthorizationViewController(paymentRequest: request)
    authVC.delegate = self
    present(authVC, animated: true, completion: nil)
}

This sample outlines how to handle the payment token once the payment request has been successfully authorized. To send the generated token to the server, execute the following request.

// Executes a process payment request on the Mobile Payments Demo Server
func paymentAuthorizationViewController(_ controller: PKPaymentAuthorizationViewController,
                                        didAuthorizePayment payment: PKPayment,
                                        completion: @escaping (PKPaymentAuthorizationStatus) -> Void) {
    // Get payment data from the token and base64 encode it
    let token = payment.token
    let paymentData = token.paymentData
    let b64TokenStr = paymentData.base64EncodedString(options: NSData.Base64EncodingOptions(rawValue: 0))
    let transactionType = self.purchaseTypeSegmentedControl.selectedSegmentIndex == 0 ? "purchase" : "pre-auth"
    let parameters = [
        "amount": self.paymentAmount,
        "transaction-type": transactionType,
        "apple-wallet": [
            "payment-token": b64TokenStr,
            "apple-pay-merchant-id": "merchant.com.mycompany.myapp"
        ]
    ] as [String : Any]

    Alamofire.request(DemoServerURLBase + "/process-payment/apple-pay",
                      method: .post,
                      parameters: parameters,
                      encoding: URLEncoding.httpBody).responseJSON { response in

        let statusCode = response.response?.statusCode

        if statusCode == 200 {
            completion(.success)
        }
        else {
            completion(.failure)
        }
    }
}

It's important that the payment_token is Base64 encoded and included in the paymentData object.

Below is an example of the paymentData object that should be submitted.

{
   "data": "...xxxxxxxxx...",
   "signature": "...xxxxxxx...",
   "header": {
       "ephemeralPublicKey" : "...xxxxx...",
       "publicKeyHash": "XwslXXdP388+XdHp4XpX1bc2Xp48XXXynlaqc4XXiIg=",
       "transactionId": "8158127844d5aa8ede2c2401e2370f24ab2d6b15a1943a1fc3ff15f6d777abxx"
   },
   "version": "EC_v1"
}

If the paymentData has a different format you will get an error like this: "Payment Token Version Not Supported: EC_vX", or this "Expected token version not found."

Test cards

You can add the test cards listed below to your Apple Wallet and use them to trigger approved responses from our gateway. You can use these test cards on your Worldline test accounts, but not on your live account. More info on using test cards within the Apple Pay sandbox environment is listed here .