{"_id":"59dfa8f45c0bae001c2e8afc","category":{"_id":"59dfa8f45c0bae001c2e8af0","version":"59dfa8f45c0bae001c2e8ae8","project":"57336fd5a6a9c40e00e13a0b","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-11-03T20:45:01.593Z","from_sync":false,"order":7,"slug":"topics","title":"Guides"},"parentDoc":null,"project":"57336fd5a6a9c40e00e13a0b","user":"560d5913af97231900938124","version":{"_id":"59dfa8f45c0bae001c2e8ae8","project":"57336fd5a6a9c40e00e13a0b","__v":1,"createdAt":"2017-10-12T17:40:04.535Z","releaseDate":"2017-10-12T17:40:04.535Z","categories":["59dfa8f45c0bae001c2e8ae9","59dfa8f45c0bae001c2e8aea","59dfa8f45c0bae001c2e8aeb","59dfa8f45c0bae001c2e8aec","59dfa8f45c0bae001c2e8aed","59dfa8f45c0bae001c2e8aee","59dfa8f45c0bae001c2e8aef","59dfa8f45c0bae001c2e8af0"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"3.23. Release","version_clean":"8976.0.0-Basics","version":"8976-Basics"},"__v":0,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-04-17T15:07:03.506Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"[Apple Pay](https://developer.apple.com/apple-pay/) is a simple, secure payment experience, allowing shoppers to purchase with credit and debit cards linked to their supported Apple devices. Apple Pay is accessible from newer versions of Safari and iOS, allowing shoppers to buy both from your website or native iOS app. \n\nThis guide covers the following: \n1. [Supported markets](#section-supported-markets)\n2. [Implementing Apple Pay in your website or iOS app](#section-implementing-apple-pay-in-your-website-or-ios-app)\n3. [Processing transactions](#section-processing-transactions)\n[block:api-header]\n{\n  \"title\": \"Supported markets\"\n}\n[/block]\n###Supported merchant countries\nMerchants domiciled in the following countries will be able to accept Apple Pay: \n* EU countries \n* United States (US) \n\n###Supported shopper countries and issuers \nShoppers whose issuing banks are located on [this list](https://support.apple.com/en-us/HT204916) will be eligible to purchase with Apple Pay. \n<br />\n[block:api-header]\n{\n  \"title\": \"Implementing Apple Pay in your website or iOS app\"\n}\n[/block]\nLearn how how to accept Apple Pay in your website or iOS app. Click the desired tab to get started. \n[block:html]\n{\n  \"html\": \"<ul class=\\\"nav nav-pills nav-justified\\\">\\n  <li class=\\\"active\\\"><a data-toggle=\\\"pill\\\" href=\\\"#web\\\">Apple Pay in your website</a></li>\\n  <li><a data-toggle=\\\"tab\\\" href=\\\"#app\\\">Apple Pay in your iOS app</a></li>\\n</ul>\\n<div class=\\\"tab-content\\\">\\n  <div id=\\\"web\\\" class=\\\"tab-pane fade in active\\\">\"\n}\n[/block]\n<br />\n[block:api-header]\n{\n  \"title\": \"Apple Pay in your website\"\n}\n[/block]\nThis section covers how to implement Apple Pay in your website for our API solutions. If you're using our BuyNow Hosted pages, visit our [Help & Support](https://support.bluesnap.com/docs/apple-pay#section-apple-pay-in-buynow-pages). \n\n*The shopper experience with Apple Pay on the web*\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/a6c8613-flow_03.PNG\",\n        \"flow 03.PNG\",\n        1045,\n        301,\n        \"#242424\"\n      ],\n      \"border\": true,\n      \"sizing\": \"full\"\n    }\n  ]\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<style>\\n  img[src=\\\"https://files.readme.io/a6c8613-flow_03.PNG\\\"] {\\n    border: 2px solid #d9d9d9; \\n  }\\n  </style>\"\n}\n[/block]\n##Implementation overview\n* [Requirements](#section-requirements)\n* [Step 1: Verify your domain](#section-step-1-verify-your-domain)\n* [Step 2: Add & display the Apple Pay button](#section-step-2-add-display-the-apple-pay-button)\n* [Step 3: Create an ApplePaySession](#section-step-3-create-an-applepaysession)\n* [Step 4: Set up the onvalidatemerchant callback](#section-step-4-set-up-the-onvalidatemerchant-callback)\n* [Step 5: Step up the onpaymentauthorized callback](#section-step-5-set-up-the-onpaymentauthorized-callback)\n* [Step 6: Show the payment sheet](#section-step-6-show-the-payment-sheet)\n* [Testing in Sandbox](#section-testing-in-sandbox)\n* [Processing Transactions](#section-processing-transactions)\n\n##Requirements\n####Shopper device requirements\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Purchasing on an iOS device\",\n    \"h-1\": \"Purchasing on a Mac\",\n    \"0-0\": \"Safari must be open on an Apple Pay-enabled iPhone.\",\n    \"0-1\": \"Safari must be open on a: \\n\\n* MacBook Pro with Touch ID, or \\n\\n* Mac model 2012 or later paired to a compatible iPhone/Apple Watch with [Handoff](https://support.apple.com/en-us/HT204681).\"\n  },\n  \"cols\": 2,\n  \"rows\": 1\n}\n[/block]\n####Apple Pay requirements\nComply with [Apple Pay Identity Guidelines](https://developer.apple.com/apple-pay/Apple-Pay-Identity-Guidelines.pdf) and [Apple Pay on the Web Human Interface Guidelines](https://developer.apple.com/apple-pay/web-human-interface-guidelines/) to ensure you're properly representing Apple Pay on your website. \n\n####Server requirements\n* All pages that include Apple Pay must be served over HTTPS.\n* Your domain must have a valid SSL certificate.\n\n####Domain verification\nYou'll need to the register all web domains that will display the Apple Pay button. See [Step 1](#section-step-1-verify-your-domain) to learn how.\n\n####Accepting donations?\nIf you're accepting donations, Apple requires that you register with [Benevity](https://causes.benevity.org/apple-pay/apple-pay-landing) before you begin implementing Apple Pay in your website.\n\n<a class=\"btn btn-primary\" href=\"#section-apple-pay-in-your-website\" role=\"button\">Back to Top</a>\n\n##Step 1: Verify your domain \nYou'll need to register all production domains that will be displaying the Apple Pay button, including both top-level domains (e.g. bluesnap.com) and sub-domains (e.g. store.bluesnap.com). \n<span></span>\n\n###1.1: Host the domain verification file on your server\n1. In your BlueSnap Console, go to **Integrations > Apple Pay**, and click **Download verification file**. The file will automatically download. \n2. Host the file at `/.well-known/apple-developer-merchantid-domain-association` on your production domain(s) that will display the Apple Pay button. \n\n###1.2 Tell BlueSnap where you're hosting the file\nYou'll need to tell BlueSnap where you're hosting the file via the BlueSnap Console or Onboarding API.\n\n**Option 1: BlueSnap Console** \n1. In your BlueSnap Console, go to **Integrations > Apple Pay**, and enter your production domain name in the **New Domain** field. \n  * Do not include `https://`\n2. Click the add **(+)** button. \n3. When you're done, click **Submit**. \n\n**Option 2: Onboarding API**\nUsing the [Onboard Apple Pay](/v4.0/docs/onboard-apple-pay-merchant) API, send a POST request to `services/2/wallets/onboarding` as in the example below. \n\n**Note**: Do not include `https://` when entering your production domain name(s). \n\nSample request: \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"walletType\\\": \\\"APPLE_PAY\\\",\\n    \\\"applePay\\\": {\\n    \\t\\\"domains\\\" : [\\\"example.com\\\", \\\"mystore.example.com\\\", \\\"bluesnap.com\\\"]\\n    }\\n}\",\n      \"language\": \"json\"\n    },\n    {\n      \"code\": \"<wallet xmlns=\\\"http://ws.plimus.com\\\">\\n   <wallet-type>APPLE_PAY</wallet-type>\\n   <apple-pay>\\n       <domain>example.com</domain>\\n       <domain>mystore.example.com</domain>\\n       <domain>bluesnap.com</domain>\\n   </apple-pay>\\n</wallet>\",\n      \"language\": \"xml\",\n      \"name\": \"XML\"\n    }\n  ]\n}\n[/block]\nA successful response will be 201 Created and will include a location header with an Onboarding ID. You may use this ID later to [retrieve your registered domain details](/v4.0/docs/retrieve-apple-pay-onboarding-information).\n\nSample response:  \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"HTTP/ 1.1 201 Created\\nLocation: https://sandbox.bluesnap.com/services/2/wallets/onboarding/385\",\n      \"language\": \"curl\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\n<a class=\"btn btn-primary\" href=\"#section-apple-pay-in-your-website\" role=\"button\">Back to Top</a>\n\n##Step 2: Add & display the Apple Pay button\nThis section covers how to add the Apple Pay button to your site, and how to detect if the shopper is using a [compatible device](#section-shopper-device-requirements) to determine if the button should be displayed. \n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Apple Pay requirements\",\n  \"body\": \"On all pages where the shopper is presented with the Apple Pay button, you're required to adhere to the [Apple Pay Identity Guidelines](https://developer.apple.com/apple-pay/Apple-Pay-Identity-Guidelines.pdf) and [Apple Pay on the Web Human Interface Guidelines](https://developer.apple.com/apple-pay/web-human-interface-guidelines/).\"\n}\n[/block]\n###2.1. Add the Apple Pay button to your site\nBegin by adding a hidden Apple Pay button to your site. Note that Safari now comes with built-in Apple Pay images, which can be accessed using `-webkit-named-image`. The following black Apple Pay button with white text can be created using this feature.  \n[block:html]\n{\n  \"html\": \"<div style=\\\"float:left;\\\">\"\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/56c5e5c-Apple_Pay_button_-_black.png\",\n        \"Apple Pay button - black.png\",\n        215,\n        47,\n        \"#040404\"\n      ],\n      \"sizing\": \"original\"\n    }\n  ]\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"</div>\\n<br />\\n<br />\\n<br />\"\n}\n[/block]\nAdding the Apple Pay button: \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<button id=\\\"apple-pay-button\\\"></button>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\nThe following CSS renders the above Apple Pay button. There are many ways to style the button. See [Apple's documentation](https://developer.apple.com/documentation/applepayjs/displaying_apple_pay_buttons) for code samples.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"#apple-pay-button {\\n    -webkit-appearance: -apple-pay-button; \\n    -apple-pay-button-type: plain;\\n    visibility: hidden; /* button is hidden by default */ \\n    display: inline-block;\\n    width: 200px;\\n    min-height: 30px;\\n    border: 1px solid black;\\n    background-image: -webkit-named-image(apple-pay-logo-white);\\n    background-size: 100% calc(60% + 2px);\\n    background-repeat: no-repeat;\\n    background-color: black;\\n    background-position: 50% 50%;\\n    border-radius: 5px;\\n    padding: 0px;\\n    margin: 5px auto;\\n}\",\n      \"language\": \"css\"\n    }\n  ]\n}\n[/block]\n###2.2: Display the Apple Pay button on a compatible device\nDetect the shopper's browser and device capabilities to determine if the Apple Pay button should be displayed. Check that `window.ApplePaySession` class exists in the browser (this class manages the Apple Pay payment process in your website). Call its `canMakePayments` method to perform a basic hardware check to see if the shopper's device is capable of purchasing with Apple Pay. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"if (window.ApplePaySession && ApplePaySession.canMakePayments()) {    \\n    // Device supports Apple Pay      \\n    // Show Apple Pay button... \\n}\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nIf you want to default to Apple Pay during your checkout flow, or if you want to add Apple Pay buttons to your product detail page, use the `canMakePaymentsWithActiveCard` method. This asynchronous call requires your BlueSnap Merchant ID, and detects both that the shopper's device supports Apple Pay and that there is at least one card provisioned in their account. If checking Apple Pay compatibility at any other point, use `canMakePayments` instead. \n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Your BlueSnap Merchant ID\",\n  \"body\": \"Use your BlueSnap Merchant ID when calling `ApplePaySession.canMakePaymentsWithActiveCard`.\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"if (window.ApplePaySession) {\\n    var merchantID = \\\"123456\\\" // your BlueSnap Merchant ID;\\n    var promise = ApplePaySession.canMakePaymentsWithActiveCard(merchantID); \\n    promise.then(function (canMakePaymentsWithActiveCard) {\\n        if (canMakePaymentsWithActiveCard) {\\n          // Device supports Apple Pay & user has at least 1 provisioned card\\n          // Show Apple Pay button... \\n        }\\n    }\\n}\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n<a class=\"btn btn-primary\" href=\"#section-apple-pay-in-your-website\" role=\"button\">Back to Top</a>\n\n##Step 3: Create an ApplePaySession\nA new `ApplePaySession` instance should be created every time the Apple Pay button is clicked/tapped.\n\nWe'll begin by adding an event listener on the button that calls `applePayClicked` when the button is clicked. This callback function is where the majority of our Apple Pay implementation will take place. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"document.getElementById('apple-pay-button').addEventListener('click', applePayClicked);\",\n      \"language\": \"javascript\",\n      \"name\": \"JavaScript\"\n    }\n  ]\n}\n[/block]\nTo begin, we'll do the following within `applePayClicked`: \n1.  Create a payment request object (an object that contains all the information needed to display the payment sheet). \n\n2. Create a new `ApplePaySession` instance. \n\nFor the payment request object, BlueSnap requires the following information to complete a transaction, in addition to Apple Pay's [requirements](https://developer.apple.com/reference/applepayjs/applepaypaymentrequest): \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Payment API\",\n    \"h-1\": \"Extended Payment API\",\n    \"0-0\": \"* requiredBillingContactFields\\n  * postalAddress\\n  * name\",\n    \"0-1\": \"* requiredBillingContactFields\\n  * postalAddress\\n  * name\\n* requiredShippingContactFields\\n  * postalAddress\\n  * email \\n  * phone\"\n  },\n  \"cols\": 2,\n  \"rows\": 1\n}\n[/block]\nNew ApplePaySession creation example: \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"function applePayClicked() {\\n  var request = {\\n    countryCode: 'US',\\n    currencyCode: 'USD',\\n    total: { label: 'Your Label', amount: '10.00', type: 'final' },\\n    supportedNetworks:[ 'amex', 'discover', 'jcb', 'masterCard', 'visa' ],\\n    merchantCapabilities: [ 'supports3DS' ],\\n    requiredBillingContactFields: [ 'postalAddress', 'name' ],\\n    requiredShippingContactFields: [ 'postalAddress', 'email', 'phone' ]\\n  }; \\n  var session = new ApplePaySession(2, request);\\n  // continued below \\n}\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nWhen creating a new `ApplePaySession` instance, a JavaScript exception will result if any of the following occur:\n* Any Apple Pay JavaScript API is called from an insecure page.\n* You pass an invalid payment request. Payment requests are invalid if they contain missing, unknown, or invalid properties, or if they have a negative total. \n\n<a class=\"btn btn-primary\" href=\"#section-apple-pay-in-your-website\" role=\"button\">Back to Top</a>\n\n##Step 4: Set up the onvalidatemerchant callback\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"[Apple's documentation](https://developer.apple.com/documentation/applepayjs/applepaysession) provides a list of events for which you may set up event handlers. We'll go over how to set up the `onvalidatemerchant` and `onpaymentauthorized` event handlers. You may set up additional event handlers if you wish.\",\n  \"title\": \"Setting up event handlers\"\n}\n[/block]\nThe callback function [`onvalidatemerchant`](https://developer.apple.com/reference/applepayjs/applepaysession/1778021-onvalidatemerchant) will be automatically called with an `event` object when the payment sheet is displayed. Merchant validation will be initiated so Apple can verify your eligibility to accept Apple Pay on your website. \n\nThe following steps outline the flow for `onvalidatemerchant`: \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Client-side:\",\n    \"h-1\": \"Server-side:\",\n    \"0-0\": \"<span><strong>1</strong>. </span>Extract the URL from `event.validationURL`.\\n<span><strong>2</strong>. </span>Send the URL to your server. <span style=\\\"float:right;\\\"><strong>⟶</strong></span>\\n<span></span>\\n<span></span>\\n<span></span>\\n<span></span>\\n<span><strong>7</strong>. </span>Pass the decoded token to your session's <span style=\\\"float:right;\\\"><strong>⟵</strong></span> `completeMerchantValidation` method as a JavaScript object.\",\n    \"0-1\": \"<span></span>\\n<span><strong>3</strong>. </span>Send a [Create Wallet](#section-create-wallet-api-call) request to BlueSnap with the URL.\\n<span><strong>4</strong>. </span>BlueSnap returns a token (a base64 encoded string) in the response. Extract this token.\\n<span><strong>5</strong>. </span>Base64 decode the token. \\n<span><strong>6</strong>. </span>Send decoded token to the client.\"\n  },\n  \"cols\": 2,\n  \"rows\": 1\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"function applePayClicked() {\\n  // continued from above \\n  session.onvalidatemerchant = function(event) {\\n    var validationURL = event.validationURL;     \\n    // send validationURL to your server...\\n    \\n    \\n    // ...return base64 decoded token\\n  var decodedToken = {base64 decoded token};\\n  session.completeMerchantValidation(JSON.parse(decodedToken)); //to abort the session, use session.abort()\\n  }; \\n  // continued below \\n}\\n    \",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nWhen called, `completeMerchantValidation` will complete the merchant validation process. The  payment sheet will update to request the shopper's authorization.\n\n###Create Wallet API call \nThe [Create Wallet](/v4.0/docs/create-wallet) request is done as part of the merchant validation process. Perform this call after you've sent the URL from `event.validationURL` to your server. \n\nThe Create Wallet request should be sent to `/services/2/wallets`, and should contain the following properties: \n* **Wallet Type** - value will be **APPLE_PAY**.\n* **Validation URL** - value extracted from `event.validationURL`.\n* **Domain Name** - the name of your domain that you verified in [Step 1](#section-step-1-verify-your-domain). \n\nSample Create Wallet requests: \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"walletType\\\": \\\"APPLE_PAY\\\", \\n  \\\"validationUrl\\\": \\\"https://apple-pay-gateway-cert.apple.com/paymentservices/startSession\\\", \\n  \\\"domainName\\\": \\\"merchant.com\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"JSON\"\n    },\n    {\n      \"code\": \"<wallet xmlns=\\\"http://ws.plimus.com\\\">\\n   <wallet-type>APPLE_PAY</wallet-type>\\n   <validation-url>https://apple-pay-gateway-cert.apple.com/paymentservices/startSession</validation-url>\\n   <domain-name>merchant.com</domain-name>\\n   <display-name>My store</display-name>\\n</wallet>\",\n      \"language\": \"xml\",\n      \"name\": \"XML\"\n    }\n  ]\n}\n[/block]\nA successful response will contain the Wallet Token (a base64 encoded string).\n\nSample Create Wallet response: \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"walletType\\\": \\\"APPLE_PAY\\\",\\n    \\\"walletToken\\\":\\\"ImRhdGEiOiJuY1AvRitIUy8zeG5ISk1pSm9RbXhCMFd\\\"\\n}\",\n      \"language\": \"json\"\n    },\n    {\n      \"code\": \"<wallet xmlns=\\\"http://ws.plimus.com\\\">\\n   <wallet-type>APPLE_PAY</wallet-type>\\n   <wallet-token>ImRhdGEiOiJuY1AvRitIUy8zeG5ISk1pSm9RbXhCMFd</wallet-token>\\n</wallet>\",\n      \"language\": \"xml\",\n      \"name\": \"XML\"\n    }\n  ]\n}\n[/block]\n<a class=\"btn btn-primary\" href=\"#section-apple-pay-in-your-website\" role=\"button\">Back to Top</a>\n\n##Step 5: Set up the onpaymentauthorized callback \nThe callback function [`onpaymentauthorized`](https://developer.apple.com/reference/applepayjs/applepaysession/1778020-onpaymentauthorized) will be automatically called with an `event` object when the shopper has authorized the payment (typically via Touch ID). \n\nThe following steps outline the flow for `onpaymentauthorized`: \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Client-side:\",\n    \"0-0\": \"<span><strong>1</strong>. </span>Extract the payment token from `event.payment`. \\n<span><strong>2</strong>. </span>Send the payment token to your server.<span style=\\\"float:right;\\\"><strong>⟶</strong></span>\\n<span></span>\\n<span></span>\\n<span><strong>6</strong>. </span>Pass an appropriate [status code](https://developer.apple.com/reference/applepayjs/applepaysession/apple_pay_status_codes) to your <span style=\\\"float:right;\\\"><strong>⟵</strong></span>session's `completePayment` method. \\n<span><strong>7</strong>. </span>Direct the shopper to the appropriate page (i.e. order confirmation page).\",\n    \"h-1\": \"Server-side:\",\n    \"0-1\": \"<span></span>\\n<span></span>\\n<span><strong>3</strong>. </span>Base64 encode the payment token. \\n<span><strong>4</strong>. </span>Send the encoded payment token to BlueSnap in a transaction request (See [Processing transactions](#section-processing-transactions)). \\n<span><strong>5</strong>. </span>Depending on BlueSnap's response, update the client.\"\n  },\n  \"cols\": 2,\n  \"rows\": 1\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"function applePayClicked() {\\n  // continued from above \\n  session.onpaymentauthorized = function(event) {\\n    var paymentToken = event.payment; \\n    // send paymentToken to server...\\n\\n \\n    // ...return a status to completePayment & direct to appropriate page   \\n    session.completePayment(ApplePaySession.STATUS_SUCCESS); //or pass another valid status code - see below\\n    window.location.href = \\\"/success.html\\\";\\n    }; \\n  // continued below\\n}\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Supported status codes for completePayment\",\n  \"body\": \"For a list of supported status codes for the `completePayment` method, click [here](https://developer.apple.com/reference/applepayjs/applepaysession/apple_pay_status_codes).\"\n}\n[/block]\n<a class=\"btn btn-primary\" href=\"#section-apple-pay-in-your-website\" role=\"button\">Back to Top</a>\n\n##Step 6: Show the payment sheet\nAfter you've added all your event handlers, call your session's `begin` method to show the payment sheet to the shopper. Note that if the session isn’t explicitly requested by the customer (i.e. inside a `click` event), the `begin` method will throw a JavaScript exception.  \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"function applePayClicked() {\\n  // continued from above\\n  session.begin(); \\n}\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nAfter the `begin` method is called, your session's `onvalidatemerchant` callback function will be called. The other callback functions will be called when their corresponding events are triggered as the shopper proceeds through checkout. \n\n<a class=\"btn btn-primary\" href=\"#section-apple-pay-in-your-website\" role=\"button\">Back to Top</a>\n\n##Testing in Sandbox \n####Getting started\n**Testing device(s)**\nMake sure you're testing on a [compatible device](#section-shopper-device-requirements). \n\n**Device region** \nTo provision test cards on your device, you'll need to make sure that your device’s region is set to a country that supports Apple Pay. Currently Apple supports testing in the following countries:\n* Australia\n* Canada\n* United Kingdom\n* United States\n\n*Note*: To test Amex cards for Apple Pay, your device region must be set to United States.\n\n**iCloud account credentials**\nContact Merchant Support at [merchants:::at:::bluesnap.com](mailto:merchants@bluesnap.com) to have Apple Pay testing enabled on your account. We'll provide you with credentials for an iCloud account that can be used for testing. \n\n*Note*: Each testing device (i.e. MacBook, iPhone, Apple Watch) must be logged in to this iCloud account. To learn about how to connect Apple Devices with Handoff, visit [Apple's Support website](https://support.apple.com/en-us/HT204681#handoff). \n\n**Test cards**\nTest cards can be found [here](/docs/test-credit-cards#section-apple-pay-test-cards). \n\n####Adding a test card to your Apple Pay wallet\n1. On your testing iOS device, open the **Settings** app and tap **iCloud** at the top. If you're signed in, tap **Sign Out** at the bottom.\n2. Log in using the iCloud credentials that you received from BlueSnap. \n3. Tap Back to go back to the first page of the Settings app. \n4. Tap **Wallet & Apple Pay**.\n5. Tap **Add Credit or Debit Card**. You'll be prompted to photograph your card. Tap **Enter Card Details Manually** instead.\n6. Enter one of the test cards found [here](/docs/test-credit-cards#section-apple-pay-test-cards).\n\n<a class=\"btn btn-primary\" href=\"#section-apple-pay-in-your-website\" role=\"button\">Back to Top</a>\n[block:html]\n{\n  \"html\": \" </div>\\n <div id=\\\"app\\\" class=\\\"tab-pane fade\\\">\"\n}\n[/block]\n<br />\n[block:api-header]\n{\n  \"title\": \"Apple Pay in your iOS app\"\n}\n[/block]\nImplement Apple Pay in your iOS app using our [iOS SDK](doc:ios-sdk) to allow shoppers to purchase physical items (such as groceries and clothing) or services (such as gym memberships and hotel reservations).\n\n*The shopper experience with Apple Pay in iOS apps*\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/67991e4-flow_02.PNG\",\n        \"flow 02.PNG\",\n        989,\n        537,\n        \"#474f4e\"\n      ],\n      \"sizing\": \"80\"\n    }\n  ]\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<style>\\n  img[src=\\\"https://files.readme.io/67991e4-flow_02.PNG\\\"] {\\n  \\tborder: 2px solid #d9d9d9; \\n  }\\n</style>\"\n}\n[/block]\n##Implementation overview\n* [Requirements](#2222)\n* [Step 1: Register for an Apple Merchant ID](#section-step-1-register-for-an-apple-merchant-id)\n* [Step 2: Create a new Apple Pay certificate](#section-step-2-create-a-new-apple-pay-certificate)\n* [Step 3: Configure Xcode](#section-step-3-configure-xcode)\n* [Testing in Sandbox](#1122) \n* [Working with payment requests](#section-working-with-payment-requests)\n* [Processing Transactions](#section-processing-transactions)\n\n##<span id=\"2222\">Requirements</span>\n###Shopper device requirements\nThe shopper must be using an iOS device (iPhone 6 or 6+, iPad Air 2, or iPad mini 3) running iOS 8.1 or later to be eligible to purchase with Apple Pay in your app.\n\n###Configuration requirements\n**Apple Developer Account**\nYou'll need an Apple Developer Account and a membership in the iOS Developer Program. If you need to become a member, you can get started [here](https://idmsa.apple.com/IDMSWebAuth/login?appIdKey=891bd3417a7776362562d2197f89480a8547b108fd934911bcbea0110d07f757&path=%2Fregister%2Fagree%2F&rv=1).\n\n**Mac with Xcode installed**\nYou'll need a Mac with Xcode 6.1 or newer installed. To install or upgrade Xcode, visit the [Mac App Store](https://itunes.apple.com/us/app/xcode/id497799835).\n\n**New Apple Pay certificate**\nTo encrypt outgoing payment information, you'll need to create a certificate that you'll upload to your BlueSnap Merchant Console. [Step 2](#section-step-2-create-a-new-apple-pay-certificate) walks you through the process. \n\n###Apple Pay requirements\nComply with [Apple Pay Identity Guidelines](https://developer.apple.com/apple-pay/Apple-Pay-Identity-Guidelines.pdf) and [iOS Human Interface Guidelines](https://developer.apple.com/ios/human-interface-guidelines/technologies/apple-pay/) to ensure you're properly representing Apple Pay in your iOS app.\n\n###Accepting donations? \nIf you're accepting donations, Apple requires that you register with [Benevity](https://causes.benevity.org/apple-pay/apple-pay-landing) before you begin implementing Apple Pay in your iOS app.\n<span></span>\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Apple Pay vs. In-App Purchases\",\n  \"body\": \"It's necessary to understand the difference between Apple Pay and In-App Purchase. Use Apple Pay within apps to sell physical goods (such as groceries, clothing, and appliances), or for services (such as club memberships, hotel reservations, and event tickets).\\n\\nUse In-App purchases to sell virtual goods (such as premium app content and subscriptions for digital content). See Apple's [In-App Purchase](https://developer.apple.com/ios/human-interface-guidelines/technologies/in-app-purchase/) for more information.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Apple Pay Developer Guide\",\n  \"body\": \"This guide is designed to work in tandem with the [Apple Pay Developer Guide](https://developer.apple.com/library/content/ApplePay_Guide/index.html#//apple_ref/doc/uid/TP40014764-CH1-SW1).\"\n}\n[/block]\n<a class=\"btn btn-primary\" href=\"#section-apple-pay-in-your-ios-app\" role=\"button\">Back to Top</a>\n\n##Step 1: Register for an Apple Merchant ID\nFollow these steps to obtain an Apple Merchant ID: \n1. From the Apple Developer Website, go to the [Registering a Merchant ID](http://developer.apple.com/account/ios/identifiers/merchant/merchantCreate.action) page.\n2. Fill out the form by entering a description and an identifier. \nYour description is for your own records and may be changed in the future. Your identifier (Merchant ID) must be unique and cannot be changed later. You'll use your Merchant ID when developing your app. \n\n##Step 2: Create a new Apple Pay certificate\nTo encrypt outgoing payment information, you'll create a certificate that you'll upload to your BlueSnap Merchant Console. This process consists of three steps: \n1. Download the CSR (certificate signing request) file from BlueSnap. \n2. Using this CSR, generate a certificate with Apple.\n3. Upload the new Apple certificate to BlueSnap. \n\n###2.1 Download the CSR file from BlueSnap\n1. In your BlueSnap Merchant Console, go to **Integrations > Apple Pay**. \n\n2. In the **iOS Applications** section, click **Download certificate signing request**, and the file will automatically download. \n\n###2.2 Generate certificate with Apple \n1. In your Apple Developer Site, go to the [Add iOS Certificate](http://developer.apple.com/account/ios/certificate/certificateCreate.action) page. \n2. From the options, select **Apple Pay Certificate**, and click **Continue**. \n3. From the dropdown, choose the Merchant ID that you created in [Step 1](#section-step-1-register-for-an-apple-merchant-id), and continue on. \n4. The next page explains that you may obtain a CSR from your Payment Provider (you obtained this from Step 2.1). The page also explains that you may create one manually - **Do not** create your own because it will not work. You need to use the CSR obtained from BlueSnap. Ignore the instructions at the bottom of the page and continue.\n5. You'll be prompted to upload the `.certSigningRequest` file. Select the file you downloaded from BlueSnap in Step 2.1 and continue. \n6. After the success page is displayed, you'll have the option to download your certificate - go ahead and do so. \n\n###2.3 Upload certificate to BlueSnap \n1. Go back to **Integrations > Apple Pay** in your BlueSnap Merchant Console.\n2. In the **iOS Applications** section, click **Choose a file**, and select the certificate you obtained from Apple. \n3. Once the certificate has uploaded, click **Submit**. \n\n<a class=\"btn btn-primary\" href=\"#section-apple-pay-in-your-ios-app\" role=\"button\">Back to Top</a>\n\n##Step 3: Configure Xcode \nTo enable Apple Pay for your app in Xcode, follow these steps: \n1. In Xcode, open your project settings, and open the **Capabilities** pane. \n2. In the Apple Pay row, enable the switch to **ON**. \n3. Select the Merchant ID that you created in [Step 1](#section-step-2-create-a-new-apple-pay-certificate). \n**Note**: Make sure that the selected Merchant ID is the same Merchant ID that you used when uploading the Apple certificate in your BlueSnap Merchant Console in Step 2. \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/158ff1b-Enable_Apple_Pay_in_Xcode.PNG\",\n        \"Enable Apple Pay in Xcode.PNG\",\n        483,\n        125,\n        \"#cecfd0\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"iOS SDK installation and usage\",\n  \"body\": \"The [SDK and a demo app are available on GitHub](https://github.com/bluesnap/bluesnap-ios/tree/master). See the [readme file](https://github.com/bluesnap/bluesnap-ios/blob/master/README.md) for detailed usage instructions.\"\n}\n[/block]\n##<span id=\"1122\">Testing in Sandbox</span>\n####Getting started\n**Testing device(s)**\nMake sure you're testing on a [compatible device](#section-shopper-device-requirements).  \n\n**Device region**\nTo provision test cards on your device, you'll need to make sure that your device’s region is set to a country that supports Apple Pay. Currently Apple supports testing in the following countries:\n* Australia\n* Canada\n* United Kingdom\n* United States\n\n*Note*: To test Amex cards for Apple Pay, your device region must be set to United States.\n\n**iTunes Connect sandbox tester account**\nYou'll need to create a sandbox tester account. We walk you through the process in [Creating a sandbox tester account](#section-creating-a-sandbox-tester-account).\n\n**Test cards**\nTest cards can be found [here](/docs/test-credit-cards#section-apple-pay-test-cards).\n\n####Creating a sandbox tester account\n1. Sign in to [iTunes Connect](https://itunesconnect.apple.com/login).\n2. On the homepage, click **Users and Roles**. \n3. Click **Sandbox Testers**.\n4. Next to **Testers**, click **⊕** to create a new test user.\n5. Complete the Tester Information form, and click **Save** when you're finished.\n\n###Adding a test card to your Apple Pay wallet\n1. On your testing iOS device, open the **Settings** app and tap **iCloud**. If you're signed in, tap **Sign Out**.\n2. Log in using your new test credentials (see [Creating a sandbox tester account](#section-creating-a-sandbox-tester-account)). \n3. Tap Back to go back to the first page of the Settings app. \n4. Tap **Wallet & Apple Pay**.\n5. Tap **Add Credit or Debit Card**. You'll be prompted to photograph your card. Tap **Enter Card Details Manually** instead.\n6. Enter one of the test cards found [here](/docs/test-credit-cards#section-apple-pay-test-cards).\n\n<a class=\"btn btn-primary\" href=\"#section-apple-pay-in-your-ios-app\" role=\"button\">Back to Top</a>\n[block:api-header]\n{\n  \"title\": \"Working with payment requests\"\n}\n[/block]\nThis section is intended for merchants not using our [iOS SDK](doc:ios-sdk). Note that we recommend using our iOS SDK to get up-and-running quickly and to offer your shopper's Apple Pay, credit cards, and PayPal in your app. \n\nWe'll cover some key topics in working with payment requests, including what information is required in the payment request, as well as how to send the payment token data to BlueSnap to complete a transaction. \n \n##Creating payment requests\nOnce you're ready to create a payment request, you'll need to include the necessary information to ensure BlueSnap can properly complete the transaction. \n\nIf you would like to learn more about the setup process for creating payment requests, refer to [Apple's documentation](https://developer.apple.com/library/content/ApplePay_Guide/CreateRequest.html#//apple_ref/doc/uid/TP40014764-CH3-SW2). \n\nBlueSnap requires the following information in the payment request to complete a transaction: \nFor a complete list of supported properties, click [here](https://developer.apple.com/reference/passkit/pkpaymentrequest).\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Payment API\",\n    \"h-1\": \"Extended Payment API\",\n    \"0-0\": \"* `countryCode`\\n* `currencyCode`\\n* `merchantCapabilities`\\n* `merchantIdentifier`\\n* `paymentSummaryItems`\\n* `supportedNetworks`\\n* `paymentSummaryItems`\\n* `requiredBillingAddressFields`\\n * `postalAddress`\\n * `name`\",\n    \"0-1\": \"* `countryCode`\\n* `currencyCode`\\n* `merchantCapabilities`\\n* `merchantIdentifier`\\n* `paymentSummaryItems`\\n* `supportedNetworks`\\n* `paymentSummaryItems`\\n* `requiredBillingAddressFields`\\n * `postalAddress`\\n * `name`\\n* `requiredShippingAddressFields`\\n * `postalAddress`\\n * `email`\\n * `phone`\"\n  },\n  \"cols\": 2,\n  \"rows\": 1\n}\n[/block]\n<a class=\"btn btn-primary\" href=\"#section-apple-pay-in-your-ios-app\" role=\"button\">Back to Top</a>\n\n##Sending payment token data to BlueSnap\nOnce you have the shopper's authorization, you're on your way to sending payment token data to BlueSnap for processing. \n\nIf you would like to learn more about the payment authorization process before moving forward, visit [Apple's documentation](https://developer.apple.com/library/content/ApplePay_Guide/Authorization.html#//apple_ref/doc/uid/TP40014764-CH4-SW3). \n\nThe payment token is an instance of the [`PKPaymentToken`](https://developer.apple.com/reference/passkit/pkpaymenttoken) class, and has a [nested structure](https://developer.apple.com/library/content/documentation/PassKit/Reference/PaymentTokenJSON/PaymentTokenJSON.html#//apple_ref/doc/uid/TP40014929). The encrypted payment data that you will send to BlueSnap for processing will first need to be extracted from this structure. \n\nThe [`paymentData`](https://developer.apple.com/reference/passkit/pkpaymenttoken/1617000-paymentdata) property of your payment token is a JSON dictionary, and it contains a `data` key. The value of this `data` key contains the encrypted payment data that you'll send to your server. After you have sent the encrypted payment data to your server, you will include it in the request when you [send to BlueSnap for processing](#section-processing-transactions). Depending on BlueSnap's response, you'll return an appropriate response in the completion handler (i.e. success, failure, etc.).\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"For more information:\",\n  \"body\": \"→ [Apple Pay Within Apps](https://developer.apple.com/videos/play/wwdc2015/702/) presentation from WWDC 2015\\n→ [Emporium: A Simple Shopping Experience with Apple Pay](https://developer.apple.com/library/content/samplecode/Emporium/Introduction/Intro.html)\"\n}\n[/block]\n##Code sample  \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"/* PKPaymentAuthorizationControllerDelegate conformance. */\\nextension PaymentHandler: PKPaymentAuthorizationControllerDelegate {\\n\\n    func paymentAuthorizationController(_ controller: PKPaymentAuthorizationController, didAuthorizePayment payment: PKPayment, completion: @escaping (PKPaymentAuthorizationStatus) -> Void)\\n    {\\n        // Perform some very basic validation on the provided contact information\\n        if payment.shippingContact?.emailAddress == nil || payment.shippingContact?.phoneNumber == nil {\\n            paymentStatus = .invalidShippingContact\\n        } else {\\n            // Here you would send the payment token to your server or payment provider to process\\n            // Once processed, return an appropriate status in the completion handler (success, failure, etc)          This is just a sample code that decodes the token and reconstruct it.  you should add some validations and make sure you pick up the information you need.\\n\\n            NSLog(\\\"Now calling BS with PKPayment:\\\")\\n            /\\n            do  {\\n                let token: PKPaymentToken = payment.token\\n                let amount = paymentSummaryItems.last?.amount\\n                let currency = paymentRequest.currencyCode\\n                let desrilaziedToken = try JSONSerialization.jsonObject(with: token.paymentData, options: JSONSerialization.ReadingOptions())\\n                let encodedPaymentToken = [\\n                    \\\"billingContact\\\":  [\\n                        \\\"emailAddress\\\" : payment.billingContact?.emailAddress,\\n                        \\\"phoneNumber\\\": payment.billingContact?.phoneNumber?.stringValue,\\n                        \\\"addressLines\\\": payment.billingContact?.postalAddress?.description                    ],\\n                    \\\"shippingContact\\\": [\\n                        \\\"emailAddress\\\": payment.shippingContact?.emailAddress,\\n                        \\\"phoneNumber\\\": payment.shippingContact?.phoneNumber?.stringValue\\n                    ],\\n                    \\n                    \\\"token\\\": [\\n                        \\\"transactionIdentifier\\\": token.transactionIdentifier,\\n                        \\\"paymentData\\\" : desrilaziedToken,\\n                        \\\"paymentMethod\\\" : [\\n                            \\\"displayName\\\": token.paymentMethod.displayName ?? \\\"unkown\\\",\\n                            \\\"network\\\": token.paymentMethod.network?._rawValue ?? \\\"unknown\\\" ,\\n                            \\\"type\\\": \\\"debit\\\",\\n                        ],\\n                    ]\\n                ] as [String : Any]\\n                \\n                let encodedPaymentTojenJson  = try JSONSerialization.data(withJSONObject: encodedPaymentToken, options: JSONSerialization.WritingOptions())\\n                let base64EncodedPaymentToken = String(data: encodedPaymentTojenJson, encoding: .utf8)!.data(using: String.Encoding.utf8)!.base64EncodedString()\\n                let body = [\\n                            \\\"amount\\\": amount,\\n                            \\\"currency\\\": currency,\\n                            \\\"wallet\\\": [\\n                                \\\"applePay\\\" : [\\n                                    \\\"encodedPaymentToken\\\": base64EncodedPaymentToken\\n                                    ]\\n                                ]\\n                           ] as [String : Any]\\n                \\n                let httpBody  = try JSONSerialization.data(withJSONObject: body, options: JSONSerialization.WritingOptions())\\n                print(String(data: httpBody, encoding: .utf8))\\n                let loginData = String(format:  \\\"%@:%@\\\",\\\"user\\\", \\\"password\\\").data(using: String.Encoding.utf8)!\\n                let base64LoginString = loginData.base64EncodedString()\\n                \\n                var request = URLRequest(url: URL(string: \\\"https://[Merchant server]\\\")!)\\n                request.httpMethod = \\\"POST\\\"\\n                \\n                request.httpBody = httpBody\\n                request.setValue(\\\"Basic \\\\(base64LoginString)\\\", forHTTPHeaderField: \\\"Authorization\\\")\\n                request.addValue(\\\"application/json\\\", forHTTPHeaderField: \\\"Content-Type\\\")\\n                request.addValue(\\\"application/json\\\", forHTTPHeaderField: \\\"Accept\\\")\\n                let task = URLSession.shared.dataTask(with: request) { data, response, error in\\n                    guard let data = data, error == nil else {\\n                        NSLog(\\\"Network error\\\")\\n                        return\\n                    }\\n                    \\n                    NSLog(response!.debugDescription)\\n                    if let httpResponse = response as? HTTPURLResponse {\\n                        NSLog(\\\"statusCode: \\\\(httpResponse.statusCode)\\\")\\n                        if httpResponse.statusCode == 200 {\\n                            self.paymentStatus = .success\\n                        }\\n                        else {\\n                            self.paymentStatus = .failure\\n                        }\\n                    }\\n                    completion(self.paymentStatus)\\n                }\\n                task.resume()\\n            \\n            }\\n            catch {\\n               NSLog(\\\"json error\\\")\\n            }\\n          \\n        }\\n    }\",\n      \"language\": \"swift\"\n    }\n  ]\n}\n[/block]\n<a class=\"btn btn-primary\" href=\"#section-apple-pay-in-your-ios-app\" role=\"button\">Back to Top</a>\n[block:html]\n{\n  \"html\": \"</div>\\n</div>\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Processing transactions\"\n}\n[/block]\nThis section covers how to send the payment token data to BlueSnap to process the transaction using the Payment API or the Extended Payment API.\n<br />\n[block:html]\n{\n  \"html\": \"<ul class=\\\"nav nav-tabs\\\">\\n  <li class=\\\"active\\\"><a data-toggle=\\\"tab\\\" href=\\\"#papiMenu\\\">Payment API</a></li>\\n  <li><a data-toggle=\\\"tab\\\" href=\\\"#extended\\\">Extended Payment API</a></li>\\n</ul>\\n\\n<div class=\\\"tab-content\\\">\\n  <div id=\\\"papiMenu\\\" class=\\\"tab-pane fade in active\\\">\"\n}\n[/block]\n<span> </span>\n##Processing transactions with the Payment API\nThe payment token data will be sent in the Encoded Payment Token property in the request.\n\n###Scenario 1: Shopper is new\nFor sales involving new shoppers, include the Encoded Payment Token property in an Auth Only, Auth Capture, or Create Subscription request. \n\nSample Auth Capture request with Apple Pay wallet: \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -v -X POST https://sandbox.bluesnap.com/services/2/transactions \\\\\\n-H 'Content-Type: application/json' \\\\\\n-H 'Accept: application/json' \\\\ \\n-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \\\\\\n-d '\\n{\\n    \\\"cardTransactionType\\\": \\\"AUTH_CAPTURE\\\",\\n    \\\"recurringTransaction\\\": \\\"ECOMMERCE\\\",\\n    \\\"softDescriptor\\\": \\\"DescTest\\\",\\n    \\\"amount\\\": 11.00,\\n    \\\"currency\\\": \\\"USD\\\",\\n    \\\"wallet\\\": {\\n      \\\"applePay\\\": {\\n        \\\"encodedPaymentToken\\\": \\\"ImRhdGEiOiJuY1AvRitIUy8zeG5bXhCMFd\\\"\\n      }\\n    }\\n}\",\n      \"language\": \"json\"\n    },\n    {\n      \"code\": \"curl -v -X POST https://sandbox.bluesnap.com/services/2/transactions \\\\\\n-H 'Content-Type: application/xml' \\\\\\n-H 'Accept: application/xml' \\\\ \\n-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \\\\\\n-d '\\n<card-transaction xmlns=\\\"http://ws.plimus.com\\\">\\n  <card-transaction-type>AUTH_CAPTURE</card-transaction-type>\\n  <recurring-transaction>ECOMMERCE</recurring-transaction>\\n  <soft-descriptor>DescTest</soft-descriptor>\\n  <amount>11.00</amount>\\n  <currency>USD</currency>\\n  <wallet>\\n    <apple-pay>\\n      <encoded-payment-token>ImRhdGEiOiJuY1AvRitIUy8zeG5bXhCMFd</encoded-payment-token>\\n    </apple-pay>\\t\\n  </wallet>\\n</card-transaction>\",\n      \"language\": \"xml\"\n    }\n  ]\n}\n[/block]\n###Scenario 2: Shopper is returning\nFor sales involving returning shoppers, include the shopper's Vaulted Shopper ID and Encoded Payment Token in the Auth Capture, Auth Only, or Create Subscription request. \n\nSample Auth Capture request with vaulted shopper and Apple Pay wallet:  \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -v -X POST https://sandbox.bluesnap.com/services/2/transactions \\\\\\n-H 'Content-Type: application/json' \\\\\\n-H 'Accept: application/json' \\\\ \\n-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \\\\\\n-d '\\n{\\n   \\\"cardTransactionType\\\": \\\"AUTH_CAPTURE\\\",\\n    \\\"recurringTransaction\\\": \\\"ECOMMERCE\\\",\\n    \\\"softDescriptor\\\": \\\"DescTest\\\",\\n    \\\"amount\\\": 11.00,\\n    \\\"currency\\\": \\\"USD\\\",\\n    \\\"vaultedShopperId\\\": 1234,\\n    \\\"wallet\\\": {\\n      \\\"applePay\\\": { \\n        \\\"encodedPaymentToken\\\": \\\"ImRhdGEiOiJuY1AvRitIUy8zeG5bXhCMFd\\\"\\n      }\\n    }\\n}\",\n      \"language\": \"json\"\n    },\n    {\n      \"code\": \"curl -v -X POST https://sandbox.bluesnap.com/services/2/transactions \\\\\\n-H 'Content-Type: application/xml' \\\\\\n-H 'Accept: application/xml' \\\\ \\n-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \\\\\\n-d '\\n<card-transaction xmlns=\\\"http://ws.plimus.com\\\">\\n  <card-transaction-type>AUTH_CAPTURE</card-transaction-type>\\n  <recurring-transaction>ECOMMERCE</recurring-transaction>\\n  <soft-descriptor>DescTest</soft-descriptor>\\n  <amount>11.00</amount>\\n  <currency>USD</currency>\\n  <vaulted-shopper-id>1234</vaulted-shopper-id>\\n  <wallet>\\n    <apple-pay>\\n      <encoded-payment-token>ImRhdGEiOiJuY1AvRitIUy8zeG5bXhCMFd</encoded-payment-token>\\n    </apple-pay>\\t\\n  </wallet>\\n</card-transaction> \",\n      \"language\": \"xml\"\n    }\n  ]\n}\n[/block]\n##For more information: \n[block:html]\n{\n  \"html\": \"<div>\\n  <div class='line'>\"\n}\n[/block]\n####Auth Capture\n[→ JSON](/v2.1/docs/auth-capture)&nbsp;&nbsp;&nbsp;&nbsp;[→ XML](/v2.0/docs/auth-capture)\n[block:html]\n{\n  \"html\": \"</div>\\n<div class='line'>\"\n}\n[/block]\n####Auth Only\n[→ JSON](/v2.1/docs/auth-only)&nbsp;&nbsp;&nbsp;&nbsp;[→ XML](/v2.0/docs/auth-only)\n[block:html]\n{\n  \"html\": \"</div>\\n<div class='line'>\"\n}\n[/block]\n####Create Subscription \n[→ JSON](/v2.1/docs/create-subscription)&nbsp;&nbsp;&nbsp;&nbsp;[→ XML](/v2.0/docs/create-subscription)\n[block:html]\n{\n  \"html\": \"</div>\\n</div>\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<style>\\n  .line {\\n    float: left; \\n    width: 25%; \\n  }\\n</style>\\n<div id='clear'>\"\n}\n[/block]\n<br />\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Working with subscriptions?\",\n  \"body\": \"Check out BlueSnap's Subscription guide: [→ JSON](/v2.1/docs/subscription-management)&nbsp;&nbsp;&nbsp;[→ XML](/v2.0/docs/subscription-management)\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"</div>\\n<style>\\n#clear {\\n  clear: both; \\n}\\n</style>\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \" </div>\\n <div id=\\\"extended\\\" class=\\\"tab-pane fade\\\">\"\n}\n[/block]\n<span></span>\n##Processing transactions with the Extended Payment API\nThe payment token data will be sent in the `encoded-payment-token` property in the request. \n\n###Scenario 1: Shopper is new\nFor sales involving new shoppers, include `encoded-payment-token` in the [Create Order and New Shopper](/v3.0/docs/create-shopper-and-order) or [Create Shopping Context](/v3.0/docs/create-shopping-context) request. \n\nSample Create Order and New Shopper request with Apple Pay: \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -v -X POST https://sandbox.bluesnap.com/services/2/batch/order-placement \\\\\\n-H 'Content-Type: application/xml' \\\\\\n-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \\\\\\n-d '\\n<batch-order xmlns=\\\"http://ws.plimus.com\\\">\\n  <order>\\n    <ordering-shopper>\\n      <web-info>\\n        <ip>62.219.121.253</ip>\\n        <remote-host>www.merchant.com</remote-host>\\n        <user-agent>Mozilla/5.0 (Linux; X11)</user-agent>\\n      </web-info>\\n      <wallet>\\n      \\t<apple-pay>\\n      \\t\\t<encoded-payment-token>eyAgDQogICAidG9rZW4iOnsgIA0KICAgICAgInBheW1lbnREYXRhIjp7ICANCiAgICAgICAgICJkYXRhIjoic1VpSnkxanlWeDFEOEluWWJFUFFRYjFSNTdGazN4QUFBQUFBQUEiLA0KICAgICAgICAgImhlYWRlciI6eyAgDQogICAgICAgICAgICAicHVi==</encoded-payment-token>\\n      \\t</apple-pay>\\n      </wallet>\\n    </ordering-shopper>\\n    <cart>\\n      <cart-item>\\n        <sku>\\n          <sku-id>2186654</sku-id>\\n        </sku>\\n        <quantity>1</quantity>\\n      </cart-item>\\n    </cart>\\n    <expected-total-price>\\n      <amount>260.00</amount>\\n      <currency>USD</currency>\\n    </expected-total-price>\\n  </order>\\n</batch-order>\\n\",\n      \"language\": \"xml\"\n    }\n  ]\n}\n[/block]\n###Scenario 2: Shopper is returning \nFor sales involving returning shoppers, include `encoded-payment-token` and `shopper-id` in the [Create Order with Existing Shopper](https://developers.bluesnap.com/v3.0/docs/create-order) or [Create Shopping Context](https://developers.bluesnap.com/v3.0/docs/create-shopping-context) request. \n\nSample Create Order with Existing Shopper request with Apple Pay: \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -v -X POST https://sandbox.bluesnap.com/services/2/orders \\\\\\n-H 'Content-Type: application/xml' \\\\\\n-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \\\\\\n-d '\\n<order xmlns=\\\"http://ws.plimus.com\\\">\\n  <ordering-shopper>\\n    <shopper-id>19575996</shopper-id>\\n    <web-info>\\n      <ip>62.219.121.253</ip>\\n      <remote-host>www.merchant.com</remote-host>\\n      <user-agent>Mozilla/5.0 (Linux; X11)</user-agent>\\n    </web-info>\\n     <wallet>\\n\\t   <apple-pay>\\n\\t\\t   <encoded-payment-token>ImRhdGEiOiJuY1AvRitIUy8zeG5bXhCMFd</encoded-payment-token>\\n   \\t   </apple-pay>\\t\\n     </wallet>\\n  </ordering-shopper>\\n  <cart>\\n    <cart-item>\\n      <sku>\\n        <sku-id>2152762</sku-id>\\n      </sku>\\n      <quantity>1</quantity>\\n    </cart-item>\\n  </cart>\\n  <expected-total-price>\\n    <amount>15.00</amount>\\n    <currency>USD</currency>\\n  </expected-total-price>\\n</order>\",\n      \"language\": \"xml\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Working with subscriptions?\",\n  \"body\": \"Check out our [Subscriptions Guide](/v3.0/docs/subscriptions-guide).\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"\\t</div>\\n</div>\"\n}\n[/block]\n<a class=\"btn btn-primary\" href=\"#section-implementing-apple-pay-in-your-website-or-ios-app\" role=\"button\">Back to Top</a>","excerpt":"Learn how to accept Apple pay in your website or iOS app.\nIf you still have questions after reading this guide, check out our answers to [common questions](https://support.bluesnap.com/docs/merchant-faqs#section-mobile-wallets).","slug":"apple-pay","type":"basic","title":"Apple Pay"}

Apple Pay

Learn how to accept Apple pay in your website or iOS app. If you still have questions after reading this guide, check out our answers to [common questions](https://support.bluesnap.com/docs/merchant-faqs#section-mobile-wallets).

Apple Pay is a simple, secure payment experience, allowing shoppers to purchase with credit and debit cards linked to their supported Apple devices. Apple Pay is accessible from newer versions of Safari and iOS, allowing shoppers to buy both from your website or native iOS app.

This guide covers the following:

  1. Supported markets
  2. Implementing Apple Pay in your website or iOS app
  3. Processing transactions

Supported markets

Supported merchant countries

Merchants domiciled in the following countries will be able to accept Apple Pay:

  • EU countries
  • United States (US)

Supported shopper countries and issuers

Shoppers whose issuing banks are located on this list will be eligible to purchase with Apple Pay.

Implementing Apple Pay in your website or iOS app

Learn how how to accept Apple Pay in your website or iOS app. Click the desired tab to get started.


Apple Pay in your website

This section covers how to implement Apple Pay in your website for our API solutions. If you're using our BuyNow Hosted pages, visit our Help & Support.

The shopper experience with Apple Pay on the web

Purchasing on an iOS device
Purchasing on a Mac

Safari must be open on an Apple Pay-enabled iPhone.

Safari must be open on a:

  • MacBook Pro with Touch ID, or

  • Mac model 2012 or later paired to a compatible iPhone/Apple Watch with Handoff.

Apple Pay requirements

Comply with Apple Pay Identity Guidelines and Apple Pay on the Web Human Interface Guidelines to ensure you're properly representing Apple Pay on your website.

Server requirements

  • All pages that include Apple Pay must be served over HTTPS.
  • Your domain must have a valid SSL certificate.

Domain verification

You'll need to the register all web domains that will display the Apple Pay button. See Step 1 to learn how.

Accepting donations?

If you're accepting donations, Apple requires that you register with Benevity before you begin implementing Apple Pay in your website.

Back to Top

Step 1: Verify your domain

You'll need to register all production domains that will be displaying the Apple Pay button, including both top-level domains (e.g. bluesnap.com) and sub-domains (e.g. store.bluesnap.com).

1.1: Host the domain verification file on your server

  1. In your BlueSnap Console, go to Integrations > Apple Pay, and click Download verification file. The file will automatically download.
  2. Host the file at /.well-known/apple-developer-merchantid-domain-association on your production domain(s) that will display the Apple Pay button.

1.2 Tell BlueSnap where you're hosting the file

You'll need to tell BlueSnap where you're hosting the file via the BlueSnap Console or Onboarding API.

Option 1: BlueSnap Console

  1. In your BlueSnap Console, go to Integrations > Apple Pay, and enter your production domain name in the New Domain field.
    • Do not include https://
  2. Click the add (+) button.
  3. When you're done, click Submit.

Option 2: Onboarding API
Using the Onboard Apple Pay API, send a POST request to services/2/wallets/onboarding as in the example below.

Note: Do not include https:// when entering your production domain name(s).

Sample request:

{
    "walletType": "APPLE_PAY",
    "applePay": {
    	"domains" : ["example.com", "mystore.example.com", "bluesnap.com"]
    }
}
<wallet xmlns="http://ws.plimus.com">
   <wallet-type>APPLE_PAY</wallet-type>
   <apple-pay>
       <domain>example.com</domain>
       <domain>mystore.example.com</domain>
       <domain>bluesnap.com</domain>
   </apple-pay>
</wallet>

A successful response will be 201 Created and will include a location header with an Onboarding ID. You may use this ID later to retrieve your registered domain details.

Sample response:

HTTP/ 1.1 201 Created
Location: https://sandbox.bluesnap.com/services/2/wallets/onboarding/385

Back to Top

Step 2: Add & display the Apple Pay button

This section covers how to add the Apple Pay button to your site, and how to detect if the shopper is using a compatible device to determine if the button should be displayed.

Apple Pay requirements

On all pages where the shopper is presented with the Apple Pay button, you're required to adhere to the Apple Pay Identity Guidelines and Apple Pay on the Web Human Interface Guidelines.

2.1. Add the Apple Pay button to your site

Begin by adding a hidden Apple Pay button to your site. Note that Safari now comes with built-in Apple Pay images, which can be accessed using -webkit-named-image. The following black Apple Pay button with white text can be created using this feature.




Adding the Apple Pay button:

<button id="apple-pay-button"></button>

The following CSS renders the above Apple Pay button. There are many ways to style the button. See Apple's documentation for code samples.

#apple-pay-button {
    -webkit-appearance: -apple-pay-button; 
    -apple-pay-button-type: plain;
    visibility: hidden; /* button is hidden by default */ 
    display: inline-block;
    width: 200px;
    min-height: 30px;
    border: 1px solid black;
    background-image: -webkit-named-image(apple-pay-logo-white);
    background-size: 100% calc(60% + 2px);
    background-repeat: no-repeat;
    background-color: black;
    background-position: 50% 50%;
    border-radius: 5px;
    padding: 0px;
    margin: 5px auto;
}

2.2: Display the Apple Pay button on a compatible device

Detect the shopper's browser and device capabilities to determine if the Apple Pay button should be displayed. Check that window.ApplePaySession class exists in the browser (this class manages the Apple Pay payment process in your website). Call its canMakePayments method to perform a basic hardware check to see if the shopper's device is capable of purchasing with Apple Pay.

if (window.ApplePaySession && ApplePaySession.canMakePayments()) {    
    // Device supports Apple Pay      
    // Show Apple Pay button... 
}

If you want to default to Apple Pay during your checkout flow, or if you want to add Apple Pay buttons to your product detail page, use the canMakePaymentsWithActiveCard method. This asynchronous call requires your BlueSnap Merchant ID, and detects both that the shopper's device supports Apple Pay and that there is at least one card provisioned in their account. If checking Apple Pay compatibility at any other point, use canMakePayments instead.

Your BlueSnap Merchant ID

Use your BlueSnap Merchant ID when calling ApplePaySession.canMakePaymentsWithActiveCard.

if (window.ApplePaySession) {
    var merchantID = "123456" // your BlueSnap Merchant ID;
    var promise = ApplePaySession.canMakePaymentsWithActiveCard(merchantID); 
    promise.then(function (canMakePaymentsWithActiveCard) {
        if (canMakePaymentsWithActiveCard) {
          // Device supports Apple Pay & user has at least 1 provisioned card
          // Show Apple Pay button... 
        }
    }
}

Back to Top

Step 3: Create an ApplePaySession

A new ApplePaySession instance should be created every time the Apple Pay button is clicked/tapped.

We'll begin by adding an event listener on the button that calls applePayClicked when the button is clicked. This callback function is where the majority of our Apple Pay implementation will take place.

document.getElementById('apple-pay-button').addEventListener('click', applePayClicked);

To begin, we'll do the following within applePayClicked:

  1. Create a payment request object (an object that contains all the information needed to display the payment sheet).

  2. Create a new ApplePaySession instance.

For the payment request object, BlueSnap requires the following information to complete a transaction, in addition to Apple Pay's requirements:

Payment API
Extended Payment API
  • requiredBillingContactFields
    • postalAddress
    • name
  • requiredBillingContactFields
    • postalAddress
    • name
  • requiredShippingContactFields
    • postalAddress
    • email
    • phone

New ApplePaySession creation example:

function applePayClicked() {
  var request = {
    countryCode: 'US',
    currencyCode: 'USD',
    total: { label: 'Your Label', amount: '10.00', type: 'final' },
    supportedNetworks:[ 'amex', 'discover', 'jcb', 'masterCard', 'visa' ],
    merchantCapabilities: [ 'supports3DS' ],
    requiredBillingContactFields: [ 'postalAddress', 'name' ],
    requiredShippingContactFields: [ 'postalAddress', 'email', 'phone' ]
  }; 
  var session = new ApplePaySession(2, request);
  // continued below 
}

When creating a new ApplePaySession instance, a JavaScript exception will result if any of the following occur:

  • Any Apple Pay JavaScript API is called from an insecure page.
  • You pass an invalid payment request. Payment requests are invalid if they contain missing, unknown, or invalid properties, or if they have a negative total.

Back to Top

Step 4: Set up the onvalidatemerchant callback

Setting up event handlers

Apple's documentation provides a list of events for which you may set up event handlers. We'll go over how to set up the onvalidatemerchant and onpaymentauthorized event handlers. You may set up additional event handlers if you wish.

The callback function onvalidatemerchant will be automatically called with an event object when the payment sheet is displayed. Merchant validation will be initiated so Apple can verify your eligibility to accept Apple Pay on your website.

The following steps outline the flow for onvalidatemerchant:

Client-side:
Server-side:

1. Extract the URL from event.validationURL.
2. Send the URL to your server.




7. Pass the decoded token to your session's completeMerchantValidation method as a JavaScript object.


3. Send a Create Wallet request to BlueSnap with the URL.
4. BlueSnap returns a token (a base64 encoded string) in the response. Extract this token.
5. Base64 decode the token.
6. Send decoded token to the client.

function applePayClicked() {
  // continued from above 
  session.onvalidatemerchant = function(event) {
    var validationURL = event.validationURL;     
    // send validationURL to your server...
    
    
    // ...return base64 decoded token
  var decodedToken = {base64 decoded token};
  session.completeMerchantValidation(JSON.parse(decodedToken)); //to abort the session, use session.abort()
  }; 
  // continued below 
}
    

When called, completeMerchantValidation will complete the merchant validation process. The payment sheet will update to request the shopper's authorization.

Create Wallet API call

The Create Wallet request is done as part of the merchant validation process. Perform this call after you've sent the URL from event.validationURL to your server.

The Create Wallet request should be sent to /services/2/wallets, and should contain the following properties:

  • Wallet Type - value will be APPLE_PAY.
  • Validation URL - value extracted from event.validationURL.
  • Domain Name - the name of your domain that you verified in Step 1.

Sample Create Wallet requests:

{
  "walletType": "APPLE_PAY", 
  "validationUrl": "https://apple-pay-gateway-cert.apple.com/paymentservices/startSession", 
  "domainName": "merchant.com"
}
<wallet xmlns="http://ws.plimus.com">
   <wallet-type>APPLE_PAY</wallet-type>
   <validation-url>https://apple-pay-gateway-cert.apple.com/paymentservices/startSession</validation-url>
   <domain-name>merchant.com</domain-name>
   <display-name>My store</display-name>
</wallet>

A successful response will contain the Wallet Token (a base64 encoded string).

Sample Create Wallet response:

{
    "walletType": "APPLE_PAY",
    "walletToken":"ImRhdGEiOiJuY1AvRitIUy8zeG5ISk1pSm9RbXhCMFd"
}
<wallet xmlns="http://ws.plimus.com">
   <wallet-type>APPLE_PAY</wallet-type>
   <wallet-token>ImRhdGEiOiJuY1AvRitIUy8zeG5ISk1pSm9RbXhCMFd</wallet-token>
</wallet>

Back to Top

Step 5: Set up the onpaymentauthorized callback

The callback function onpaymentauthorized will be automatically called with an event object when the shopper has authorized the payment (typically via Touch ID).

The following steps outline the flow for onpaymentauthorized:

Client-side:
Server-side:

1. Extract the payment token from event.payment.
2. Send the payment token to your server.


6. Pass an appropriate status code to your session's completePayment method.
7. Direct the shopper to the appropriate page (i.e. order confirmation page).



3. Base64 encode the payment token.
4. Send the encoded payment token to BlueSnap in a transaction request (See Processing transactions).
5. Depending on BlueSnap's response, update the client.

function applePayClicked() {
  // continued from above 
  session.onpaymentauthorized = function(event) {
    var paymentToken = event.payment; 
    // send paymentToken to server...

 
    // ...return a status to completePayment & direct to appropriate page   
    session.completePayment(ApplePaySession.STATUS_SUCCESS); //or pass another valid status code - see below
    window.location.href = "/success.html";
    }; 
  // continued below
}

Supported status codes for completePayment

For a list of supported status codes for the completePayment method, click here.

Back to Top

Step 6: Show the payment sheet

After you've added all your event handlers, call your session's begin method to show the payment sheet to the shopper. Note that if the session isn’t explicitly requested by the customer (i.e. inside a click event), the begin method will throw a JavaScript exception.

function applePayClicked() {
  // continued from above
  session.begin(); 
}

After the begin method is called, your session's onvalidatemerchant callback function will be called. The other callback functions will be called when their corresponding events are triggered as the shopper proceeds through checkout.

Back to Top

Testing in Sandbox

Getting started

Testing device(s)
Make sure you're testing on a compatible device.

Device region
To provision test cards on your device, you'll need to make sure that your device’s region is set to a country that supports Apple Pay. Currently Apple supports testing in the following countries:

  • Australia
  • Canada
  • United Kingdom
  • United States

Note: To test Amex cards for Apple Pay, your device region must be set to United States.

iCloud account credentials
Contact Merchant Support at merchants@bluesnap.com to have Apple Pay testing enabled on your account. We'll provide you with credentials for an iCloud account that can be used for testing.

Note: Each testing device (i.e. MacBook, iPhone, Apple Watch) must be logged in to this iCloud account. To learn about how to connect Apple Devices with Handoff, visit Apple's Support website.

Test cards
Test cards can be found here.

Adding a test card to your Apple Pay wallet

  1. On your testing iOS device, open the Settings app and tap iCloud at the top. If you're signed in, tap Sign Out at the bottom.
  2. Log in using the iCloud credentials that you received from BlueSnap.
  3. Tap Back to go back to the first page of the Settings app.
  4. Tap Wallet & Apple Pay.
  5. Tap Add Credit or Debit Card. You'll be prompted to photograph your card. Tap Enter Card Details Manually instead.
  6. Enter one of the test cards found here.

Back to Top


Apple Pay in your iOS app

Implement Apple Pay in your iOS app using our iOS SDK to allow shoppers to purchase physical items (such as groceries and clothing) or services (such as gym memberships and hotel reservations).

The shopper experience with Apple Pay in iOS apps

Implementation overview

Requirements

Shopper device requirements

The shopper must be using an iOS device (iPhone 6 or 6+, iPad Air 2, or iPad mini 3) running iOS 8.1 or later to be eligible to purchase with Apple Pay in your app.

Configuration requirements

Apple Developer Account
You'll need an Apple Developer Account and a membership in the iOS Developer Program. If you need to become a member, you can get started here.

Mac with Xcode installed
You'll need a Mac with Xcode 6.1 or newer installed. To install or upgrade Xcode, visit the Mac App Store.

New Apple Pay certificate
To encrypt outgoing payment information, you'll need to create a certificate that you'll upload to your BlueSnap Merchant Console. Step 2 walks you through the process.

Apple Pay requirements

Comply with Apple Pay Identity Guidelines and iOS Human Interface Guidelines to ensure you're properly representing Apple Pay in your iOS app.

Accepting donations?

If you're accepting donations, Apple requires that you register with Benevity before you begin implementing Apple Pay in your iOS app.

Apple Pay vs. In-App Purchases

It's necessary to understand the difference between Apple Pay and In-App Purchase. Use Apple Pay within apps to sell physical goods (such as groceries, clothing, and appliances), or for services (such as club memberships, hotel reservations, and event tickets).

Use In-App purchases to sell virtual goods (such as premium app content and subscriptions for digital content). See Apple's In-App Purchase for more information.

Apple Pay Developer Guide

This guide is designed to work in tandem with the Apple Pay Developer Guide.

Back to Top

Step 1: Register for an Apple Merchant ID

Follow these steps to obtain an Apple Merchant ID:

  1. From the Apple Developer Website, go to the Registering a Merchant ID page.
  2. Fill out the form by entering a description and an identifier.
    Your description is for your own records and may be changed in the future. Your identifier (Merchant ID) must be unique and cannot be changed later. You'll use your Merchant ID when developing your app.

Step 2: Create a new Apple Pay certificate

To encrypt outgoing payment information, you'll create a certificate that you'll upload to your BlueSnap Merchant Console. This process consists of three steps:

  1. Download the CSR (certificate signing request) file from BlueSnap.
  2. Using this CSR, generate a certificate with Apple.
  3. Upload the new Apple certificate to BlueSnap.

2.1 Download the CSR file from BlueSnap

  1. In your BlueSnap Merchant Console, go to Integrations > Apple Pay.

  2. In the iOS Applications section, click Download certificate signing request, and the file will automatically download.

2.2 Generate certificate with Apple

  1. In your Apple Developer Site, go to the Add iOS Certificate page.
  2. From the options, select Apple Pay Certificate, and click Continue.
  3. From the dropdown, choose the Merchant ID that you created in Step 1, and continue on.
  4. The next page explains that you may obtain a CSR from your Payment Provider (you obtained this from Step 2.1). The page also explains that you may create one manually - Do not create your own because it will not work. You need to use the CSR obtained from BlueSnap. Ignore the instructions at the bottom of the page and continue.
  5. You'll be prompted to upload the .certSigningRequest file. Select the file you downloaded from BlueSnap in Step 2.1 and continue.
  6. After the success page is displayed, you'll have the option to download your certificate - go ahead and do so.

2.3 Upload certificate to BlueSnap

  1. Go back to Integrations > Apple Pay in your BlueSnap Merchant Console.
  2. In the iOS Applications section, click Choose a file, and select the certificate you obtained from Apple.
  3. Once the certificate has uploaded, click Submit.

Back to Top

Step 3: Configure Xcode

To enable Apple Pay for your app in Xcode, follow these steps:

  1. In Xcode, open your project settings, and open the Capabilities pane.
  2. In the Apple Pay row, enable the switch to ON.
  3. Select the Merchant ID that you created in Step 1.
    Note: Make sure that the selected Merchant ID is the same Merchant ID that you used when uploading the Apple certificate in your BlueSnap Merchant Console in Step 2.

iOS SDK installation and usage

The SDK and a demo app are available on GitHub. See the readme file for detailed usage instructions.

Testing in Sandbox

Getting started

Testing device(s)
Make sure you're testing on a compatible device.

Device region
To provision test cards on your device, you'll need to make sure that your device’s region is set to a country that supports Apple Pay. Currently Apple supports testing in the following countries:

  • Australia
  • Canada
  • United Kingdom
  • United States

Note: To test Amex cards for Apple Pay, your device region must be set to United States.

iTunes Connect sandbox tester account
You'll need to create a sandbox tester account. We walk you through the process in Creating a sandbox tester account.

Test cards
Test cards can be found here.

Creating a sandbox tester account

  1. Sign in to iTunes Connect.
  2. On the homepage, click Users and Roles.
  3. Click Sandbox Testers.
  4. Next to Testers, click to create a new test user.
  5. Complete the Tester Information form, and click Save when you're finished.

Adding a test card to your Apple Pay wallet

  1. On your testing iOS device, open the Settings app and tap iCloud. If you're signed in, tap Sign Out.
  2. Log in using your new test credentials (see Creating a sandbox tester account).
  3. Tap Back to go back to the first page of the Settings app.
  4. Tap Wallet & Apple Pay.
  5. Tap Add Credit or Debit Card. You'll be prompted to photograph your card. Tap Enter Card Details Manually instead.
  6. Enter one of the test cards found here.

Back to Top

Working with payment requests

This section is intended for merchants not using our iOS SDK. Note that we recommend using our iOS SDK to get up-and-running quickly and to offer your shopper's Apple Pay, credit cards, and PayPal in your app.

We'll cover some key topics in working with payment requests, including what information is required in the payment request, as well as how to send the payment token data to BlueSnap to complete a transaction.

Creating payment requests

Once you're ready to create a payment request, you'll need to include the necessary information to ensure BlueSnap can properly complete the transaction.

If you would like to learn more about the setup process for creating payment requests, refer to Apple's documentation.

BlueSnap requires the following information in the payment request to complete a transaction:
For a complete list of supported properties, click here.

Payment API
Extended Payment API
  • countryCode
  • currencyCode
  • merchantCapabilities
  • merchantIdentifier
  • paymentSummaryItems
  • supportedNetworks
  • paymentSummaryItems
  • requiredBillingAddressFields
    • postalAddress
    • name
  • countryCode
  • currencyCode
  • merchantCapabilities
  • merchantIdentifier
  • paymentSummaryItems
  • supportedNetworks
  • paymentSummaryItems
  • requiredBillingAddressFields
    • postalAddress
    • name
  • requiredShippingAddressFields
    • postalAddress
    • email
    • phone

Back to Top

Sending payment token data to BlueSnap

Once you have the shopper's authorization, you're on your way to sending payment token data to BlueSnap for processing.

If you would like to learn more about the payment authorization process before moving forward, visit Apple's documentation.

The payment token is an instance of the PKPaymentToken class, and has a nested structure. The encrypted payment data that you will send to BlueSnap for processing will first need to be extracted from this structure.

The paymentData property of your payment token is a JSON dictionary, and it contains a data key. The value of this data key contains the encrypted payment data that you'll send to your server. After you have sent the encrypted payment data to your server, you will include it in the request when you send to BlueSnap for processing. Depending on BlueSnap's response, you'll return an appropriate response in the completion handler (i.e. success, failure, etc.).

For more information:

Apple Pay Within Apps presentation from WWDC 2015
Emporium: A Simple Shopping Experience with Apple Pay

Code sample

/* PKPaymentAuthorizationControllerDelegate conformance. */
extension PaymentHandler: PKPaymentAuthorizationControllerDelegate {

    func paymentAuthorizationController(_ controller: PKPaymentAuthorizationController, didAuthorizePayment payment: PKPayment, completion: @escaping (PKPaymentAuthorizationStatus) -> Void)
    {
        // Perform some very basic validation on the provided contact information
        if payment.shippingContact?.emailAddress == nil || payment.shippingContact?.phoneNumber == nil {
            paymentStatus = .invalidShippingContact
        } else {
            // Here you would send the payment token to your server or payment provider to process
            // Once processed, return an appropriate status in the completion handler (success, failure, etc)          This is just a sample code that decodes the token and reconstruct it.  you should add some validations and make sure you pick up the information you need.

            NSLog("Now calling BS with PKPayment:")
            /
            do  {
                let token: PKPaymentToken = payment.token
                let amount = paymentSummaryItems.last?.amount
                let currency = paymentRequest.currencyCode
                let desrilaziedToken = try JSONSerialization.jsonObject(with: token.paymentData, options: JSONSerialization.ReadingOptions())
                let encodedPaymentToken = [
                    "billingContact":  [
                        "emailAddress" : payment.billingContact?.emailAddress,
                        "phoneNumber": payment.billingContact?.phoneNumber?.stringValue,
                        "addressLines": payment.billingContact?.postalAddress?.description                    ],
                    "shippingContact": [
                        "emailAddress": payment.shippingContact?.emailAddress,
                        "phoneNumber": payment.shippingContact?.phoneNumber?.stringValue
                    ],
                    
                    "token": [
                        "transactionIdentifier": token.transactionIdentifier,
                        "paymentData" : desrilaziedToken,
                        "paymentMethod" : [
                            "displayName": token.paymentMethod.displayName ?? "unkown",
                            "network": token.paymentMethod.network?._rawValue ?? "unknown" ,
                            "type": "debit",
                        ],
                    ]
                ] as [String : Any]
                
                let encodedPaymentTojenJson  = try JSONSerialization.data(withJSONObject: encodedPaymentToken, options: JSONSerialization.WritingOptions())
                let base64EncodedPaymentToken = String(data: encodedPaymentTojenJson, encoding: .utf8)!.data(using: String.Encoding.utf8)!.base64EncodedString()
                let body = [
                            "amount": amount,
                            "currency": currency,
                            "wallet": [
                                "applePay" : [
                                    "encodedPaymentToken": base64EncodedPaymentToken
                                    ]
                                ]
                           ] as [String : Any]
                
                let httpBody  = try JSONSerialization.data(withJSONObject: body, options: JSONSerialization.WritingOptions())
                print(String(data: httpBody, encoding: .utf8))
                let loginData = String(format:  "%@:%@","user", "password").data(using: String.Encoding.utf8)!
                let base64LoginString = loginData.base64EncodedString()
                
                var request = URLRequest(url: URL(string: "https://[Merchant server]")!)
                request.httpMethod = "POST"
                
                request.httpBody = httpBody
                request.setValue("Basic \(base64LoginString)", forHTTPHeaderField: "Authorization")
                request.addValue("application/json", forHTTPHeaderField: "Content-Type")
                request.addValue("application/json", forHTTPHeaderField: "Accept")
                let task = URLSession.shared.dataTask(with: request) { data, response, error in
                    guard let data = data, error == nil else {
                        NSLog("Network error")
                        return
                    }
                    
                    NSLog(response!.debugDescription)
                    if let httpResponse = response as? HTTPURLResponse {
                        NSLog("statusCode: \(httpResponse.statusCode)")
                        if httpResponse.statusCode == 200 {
                            self.paymentStatus = .success
                        }
                        else {
                            self.paymentStatus = .failure
                        }
                    }
                    completion(self.paymentStatus)
                }
                task.resume()
            
            }
            catch {
               NSLog("json error")
            }
          
        }
    }

Processing transactions

This section covers how to send the payment token data to BlueSnap to process the transaction using the Payment API or the Extended Payment API.

Processing transactions with the Payment API

The payment token data will be sent in the Encoded Payment Token property in the request.

Scenario 1: Shopper is new

For sales involving new shoppers, include the Encoded Payment Token property in an Auth Only, Auth Capture, or Create Subscription request.

Sample Auth Capture request with Apple Pay wallet:

curl -v -X POST https://sandbox.bluesnap.com/services/2/transactions \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
    "cardTransactionType": "AUTH_CAPTURE",
    "recurringTransaction": "ECOMMERCE",
    "softDescriptor": "DescTest",
    "amount": 11.00,
    "currency": "USD",
    "wallet": {
      "applePay": {
        "encodedPaymentToken": "ImRhdGEiOiJuY1AvRitIUy8zeG5bXhCMFd"
      }
    }
}
curl -v -X POST https://sandbox.bluesnap.com/services/2/transactions \
-H 'Content-Type: application/xml' \
-H 'Accept: application/xml' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<card-transaction xmlns="http://ws.plimus.com">
  <card-transaction-type>AUTH_CAPTURE</card-transaction-type>
  <recurring-transaction>ECOMMERCE</recurring-transaction>
  <soft-descriptor>DescTest</soft-descriptor>
  <amount>11.00</amount>
  <currency>USD</currency>
  <wallet>
    <apple-pay>
      <encoded-payment-token>ImRhdGEiOiJuY1AvRitIUy8zeG5bXhCMFd</encoded-payment-token>
    </apple-pay>	
  </wallet>
</card-transaction>

Scenario 2: Shopper is returning

For sales involving returning shoppers, include the shopper's Vaulted Shopper ID and Encoded Payment Token in the Auth Capture, Auth Only, or Create Subscription request.

Sample Auth Capture request with vaulted shopper and Apple Pay wallet:

curl -v -X POST https://sandbox.bluesnap.com/services/2/transactions \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
   "cardTransactionType": "AUTH_CAPTURE",
    "recurringTransaction": "ECOMMERCE",
    "softDescriptor": "DescTest",
    "amount": 11.00,
    "currency": "USD",
    "vaultedShopperId": 1234,
    "wallet": {
      "applePay": { 
        "encodedPaymentToken": "ImRhdGEiOiJuY1AvRitIUy8zeG5bXhCMFd"
      }
    }
}
curl -v -X POST https://sandbox.bluesnap.com/services/2/transactions \
-H 'Content-Type: application/xml' \
-H 'Accept: application/xml' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<card-transaction xmlns="http://ws.plimus.com">
  <card-transaction-type>AUTH_CAPTURE</card-transaction-type>
  <recurring-transaction>ECOMMERCE</recurring-transaction>
  <soft-descriptor>DescTest</soft-descriptor>
  <amount>11.00</amount>
  <currency>USD</currency>
  <vaulted-shopper-id>1234</vaulted-shopper-id>
  <wallet>
    <apple-pay>
      <encoded-payment-token>ImRhdGEiOiJuY1AvRitIUy8zeG5bXhCMFd</encoded-payment-token>
    </apple-pay>	
  </wallet>
</card-transaction> 

For more information:

Auth Capture

→ JSON    → XML

Auth Only

→ JSON    → XML

Create Subscription

→ JSON    → XML


Working with subscriptions?

Check out BlueSnap's Subscription guide: → JSON   → XML

Processing transactions with the Extended Payment API

The payment token data will be sent in the encoded-payment-token property in the request.

Scenario 1: Shopper is new

For sales involving new shoppers, include encoded-payment-token in the Create Order and New Shopper or Create Shopping Context request.

Sample Create Order and New Shopper request with Apple Pay:

curl -v -X POST https://sandbox.bluesnap.com/services/2/batch/order-placement \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<batch-order xmlns="http://ws.plimus.com">
  <order>
    <ordering-shopper>
      <web-info>
        <ip>62.219.121.253</ip>
        <remote-host>www.merchant.com</remote-host>
        <user-agent>Mozilla/5.0 (Linux; X11)</user-agent>
      </web-info>
      <wallet>
      	<apple-pay>
      		<encoded-payment-token>eyAgDQogICAidG9rZW4iOnsgIA0KICAgICAgInBheW1lbnREYXRhIjp7ICANCiAgICAgICAgICJkYXRhIjoic1VpSnkxanlWeDFEOEluWWJFUFFRYjFSNTdGazN4QUFBQUFBQUEiLA0KICAgICAgICAgImhlYWRlciI6eyAgDQogICAgICAgICAgICAicHVi==</encoded-payment-token>
      	</apple-pay>
      </wallet>
    </ordering-shopper>
    <cart>
      <cart-item>
        <sku>
          <sku-id>2186654</sku-id>
        </sku>
        <quantity>1</quantity>
      </cart-item>
    </cart>
    <expected-total-price>
      <amount>260.00</amount>
      <currency>USD</currency>
    </expected-total-price>
  </order>
</batch-order>

Scenario 2: Shopper is returning

For sales involving returning shoppers, include encoded-payment-token and shopper-id in the Create Order with Existing Shopper or Create Shopping Context request.

Sample Create Order with Existing Shopper request with Apple Pay:

curl -v -X POST https://sandbox.bluesnap.com/services/2/orders \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<order xmlns="http://ws.plimus.com">
  <ordering-shopper>
    <shopper-id>19575996</shopper-id>
    <web-info>
      <ip>62.219.121.253</ip>
      <remote-host>www.merchant.com</remote-host>
      <user-agent>Mozilla/5.0 (Linux; X11)</user-agent>
    </web-info>
     <wallet>
	   <apple-pay>
		   <encoded-payment-token>ImRhdGEiOiJuY1AvRitIUy8zeG5bXhCMFd</encoded-payment-token>
   	   </apple-pay>	
     </wallet>
  </ordering-shopper>
  <cart>
    <cart-item>
      <sku>
        <sku-id>2152762</sku-id>
      </sku>
      <quantity>1</quantity>
    </cart-item>
  </cart>
  <expected-total-price>
    <amount>15.00</amount>
    <currency>USD</currency>
  </expected-total-price>
</order>

Working with subscriptions?

Check out our Subscriptions Guide.