Transcription

Apple PaySimple Order APIJCN GatewayDeveloper Guide

2021. Cybersource Corporation. All rights reserved.Cybersource Corporation (Cybersource) furnishes this document and the software described in this document underthe applicable agreement between the reader of this document (You) and Cybersource (Agreement). You may use thisdocument and/or software only in accordance with the terms of the Agreement. Except as expressly set forth in theAgreement, the information contained in this document is subject to change without notice and therefore should not beinterpreted in any way as a guarantee or warranty by Cybersource. Cybersource assumes no responsibility or liabilityfor any errors that may appear in this document. The copyrighted software that accompanies this document is licensedto You for use only in strict accordance with the Agreement. You should read the Agreement carefully before using thesoftware. Except as permitted by the Agreement, You may not reproduce any part of this document, store this documentin a retrieval system, or transmit this document, in any form or by any means, electronic, mechanical, recording, orotherwise, without the prior written consent of Cybersource.Restricted Rights LegendsFor Government or defense agencies: Use, duplication, or disclosure by the Government or defense agencies is subject torestrictions as set forth the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 and in similarclauses in the FAR and NASA FAR Supplement.For civilian agencies: Use, reproduction, or disclosure is subject to restrictions set forth in subparagraphs (a) through (d)of the Commercial Computer Software Restricted Rights clause at 52.227-19 and the limitations set forth in CybersourceCorporation's standard commercial agreement for this software. Unpublished rights reserved under the copyright laws ofthe United States.TrademarksAuthorize.Net, eCheck.Net, and The Power of Payment are registered trademarks of Cybersource Corporation.Cybersource, Cybersource Payment Manager, Cybersource Risk Manager, Cybersource Decision Manager, andCybersource Connect are trademarks and/or service marks of Cybersource Corporation. Visa, Visa International,Cybersource, the Visa logo, and the Cybersource logo are the registered trademarks of Visa International in the UnitedStates and other countries. All other trademarks, service marks, registered marks, or registered service marks are theproperty of their respective owners.Version: 21.04Apple Pay 2

ContentsRecent Revisions to This Document. 4About This Guide. 5Getting Started.6Requirements for Using Apple Pay.6Supported Processors.7Enrolling in Apple Pay.7Generating a New CSR.8Transaction Request Report. 8Apple Pay Integrations. 9In-App Transactions Using the Cybersource API. 9Cybersource Decryption (In-App Transactions). 10Merchant Decryption (In-App Transactions). 11Web Transactions.12Cybersource Decryption (Web Transactions). 13Merchant Decryption (Web Transactions). 14Configuring Your Apple Pay Requirements. 14Setting Up Apple Pay JavaScript.16Requesting Services. 18Requesting the Authorization Service. 18Using the Cybersource Decryption Method. 18Using the Merchant Decryption Method. 20Requesting Additional Services. 23API Fields. 24Apple Pay - Contents 3

Recent Revisions to This Document21.04Changed the name of the merchantURL field to merchantDomainName. See the API FieldReference for the Simple Order API.21.03Added the tokenSource networkTokenOption field. See the API Field Reference for the SimpleOrder API.21.02Updated the card type field. See the API Field Reference for the Simple Order API.21.01Added the merchantUrl field. See the API Field Reference for the Simple Order API.20.03Updated information about recurring payments. See Supported Processors (on page 7).20.02This revision contains only editorial changes and no technical updates.20.01This revision contains only editorial changes and no technical updates.Apple Pay - Recent Revisions to This Document 4

About This GuideThis section provides you with information about the structure and content within this guide.Audience and PurposeThis document is written for merchants who want to use Apple Pay in an iOS application and useinformation from Apple to process payments through Cybersource. This document provides anoverview for integrating Apple and Cybersource services into an order management system.ConventionsThe following special statements are used in this document:Important: An Important statement contains information essential to successfullycompleting a task or learning a concept.Warning: A Warning contains information or instructions, which, if not heeded, can result ina security risk, irreversible loss of data, or significant cost in time or revenue or both.Related DocumentationFor further technical documentation, visit the Cybersource Technical Documentation ustomer SupportFor support information about any service, visit the Support Center:http://www.cybersource.com/supportApple Pay - About This Guide 5

Getting StartedRequirements for Using Apple PayIn order to use the Cybersource platform to process Apple Pay transactions, you must have: A Cybersource account.If you do not already have a Cybersource account, contact your local Cybersource salesrepresentative. A merchant account with a supported processor. See Supported Processors (on page 7). An Admin or Team Agent user of the Apple Pay Developer account.Important:Apple Pay relies on authorizations with payment network tokens. You can sign up for Apple Payonly when both of the following statements are true: Your processor supports payment network tokens. Cybersource supports payment network tokens with your processor.If one or both of the preceding statements are not true, you must take one of the following actionsbefore you can sign up for Apple Pay: Obtain a new merchant account with a processor that supports payment network tokens. Wait until your processor supports payment network tokens.Related informationSupported Processors (on page 7)Apple Pay - Getting Started 6

Supported ProcessorsMerchant-initiated transactions, multiple partial captures, and subsequent authorizations aredescribed in the Authorizations with Payment Network Tokens guide. Recurring payments and splitshipments are described in the Credit Card Services guide.ProcessorJCN GatewayCard Types JCBOptional Features Multiple partialcaptures SubsequentauthorizationsRelated informationAuthorizations with Payment Network Tokens Developer and Credit Card Services guides (availableon the Payment Services Credit Card Services page)Enrolling in Apple Pay1. Log in to the Business Center: Test: https://ebctest.cybersource.com/ebc2 Production: https://ebc.cybersource.com/ebc22. On the left navigation panel, click the Payment Configuration icon.3. Click Digital Payment Solution. The Digital Payments page appears.4. Click Configure. The Apple Pay Registration panel opens.5. Enter your Apple Merchant ID.6. Click Generate New CSR.7. To download your CSR, click the Download icon next to the key.8. Follow your browser's instructions to save and open the file.9. Complete the enrollment process by submitting your CSR to Apple.10. For information about adding certificates to your Apple Merchant ID, refer to the Apple PayPassKit: 11. Test your software by following the steps in Requesting the Authorization Service (on page18).Important: If you are using a Cybersource test account, you must connect to the Appledeveloper system and not to the Apple production system.After you complete your testing, you must create a new CSR for the Cybersource productionsystem, and you must use that CSR for the Apple production system. Until you performthese steps, you cannot enable payments in your iOS application.12. Repeat Steps 1 through 11 with your Cybersource production account and the Appleproduction account.Apple Pay - Getting Started 7

Generating a New CSR1. Log in to the Business Center: Test: https://ebctest.cybersource.com/ebc2 Production: https://ebc.cybersource.com/ebc22. On the left navigation panel, click the Payment Configuration icon.3. Click Digital Payment Solution. The Digital Payments page appears.4. Click Configure. The Apple Pay Registration panel opens.5. To download your CSR, click the Download icon next to the key.6. Follow your browser's instructions to save and open the file.7. To edit your Apple Merchant ID, click the Edit icon. The Edit CSR panel opens.8. Modify your merchant ID as necessary, and click Update.Transaction Request ReportThrough the Business Center, you can use the Transaction Request Report to obtain informationabout your transactions: Use the Transaction Search page to identify Apple transactions. You can search for transactionsby date, application type, customer name, and other transaction identifiers. For information about the Transaction Request Report, see the Business Center Reporting UserGuide.Apple Pay - Getting Started 8

Apple Pay IntegrationsIn-App Transactions Using the Cybersource APIThis section describes how in-app transactions are processed using the Cybersource API: Cybersource Decryption (In-App Transactions) (on page 10) Merchant Decryption (In-App Transactions) (on page 11)For information about processing web transactions, refer to: Cybersource Decryption (Web Transactions) (on page 13) Merchant Decryption (Web Transactions) (on page 14)Apple Pay - Apple Pay Integrations 9

Cybersource Decryption (In-App Transactions)1. When the customer chooses to pay with Apple Pay, you use the Apple PassKit Framework torequest the encrypted payment data from Apple.2. Apple uses the Secure Element to create a payment token (the PKPaymentToken structure)and encrypt the token’s payment data (the paymentData field of the PKPaymentTokenstructure) before it sends your application.3. You forward the encrypted payment data to your order management system.4. Using the Cybersource API, you submit the authorization request. In theencryptedPayment data field, include the Base64-encoded value obtained from thepaymentData field of the PKPaymentToken structure.5. Cybersource decrypts the payment data and forwards the information to the payment network,which includes your processor and the relevant payment card company.Important: You must use the Business Center or one of the Cybersource API servicesto capture, credit, or void the authorization. Refer to the Credit Card Services guide (seeRelated information below) for information.Related informationRequesting the Authorization Service for JCB Transactions (Cybersource Decryption) (on page 18)Credit Card Services guide on Payment Services Credit Card Services pageApple Pay - Apple Pay Integrations 10

Merchant Decryption (In-App Transactions)1. When the customer chooses to pay with Apple Pay, you use the Apple PassKit Framework torequest the encrypted payment data from Apple.2. Apple uses the Secure Element to create a payment token (the PKPaymentToken structure)and encrypt the token’s payment data (the paymentData field of the PKPaymentTokenstructure) before it sends your application.3. You forward the encrypted payment data to your order management system to decrypt. Forinformation on decryption, see: TokenJSON.html#//apple ref/doc/uid/TP40014929-CH8-SW14. Using the Cybersource API, you submit the authorization request and include the decryptedpayment data.5. Cybersource forwards the information to the payment network, which includes your processorand the relevant payment card company.Important: You must use the Business Center or one of the Cybersource API servicesto capture, credit, or void the authorization. Refer to the Credit Card Services guide (seeRelated information below) for information.Related informationRequesting the Authorization Service for JCB Transactions (Merchant Decryption) (on page 20)Credit Card Services guide on Payment Services Credit Card Services pageApple Pay - Apple Pay Integrations 11

Web TransactionsThis section describes how web transactions are processed using the Cybersource API: Cybersource Decryption (Web Transactions) (on page 13) Merchant Decryption (Web Transactions) (on page 14)For information about processing in-app transactions, refer to: Cybersource Decryption (In-App Transactions) (on page 10) Merchant Decryption (In-App Transactions) (on page 11)Apple Pay - Apple Pay Integrations 12

Cybersource Decryption (Web Transactions)1. When the customer chooses to pay with Apple Pay, you use the Apple Pay JavaScript to requestthe encrypted payment data from Apple.2. Apple uses the Secure Element to create a payment token (the PKPaymentToken structure)and encrypt the token’s payment data (the paymentData field of the PKPaymentTokenstructure) before it sends your application using the onpaymentauthorized callback function.3. You forward the encrypted payment data to your order management system.4. Using the Cybersource API, you submit the authorization request. In theencryptedPayment data field, include the Base64-encoded value obtained from thepaymentData field of the PKPaymentToken structure.5. Cybersource decrypts the payment data and forwards the information to the payment network,which includes your processor and the relevant payment card company.Important: You must use the Business Center or one of the Cybersource API servicesto capture, credit, or void the authorization. Refer to the Credit Card Services guide (seeRelated information below) for information.Related informationCredit Card Services guide on the Payment Services Credit Card Services pageApple Pay - Apple Pay Integrations 13

Merchant Decryption (Web Transactions)1. When the customer chooses to pay with Apple Pay, you use the Apple Pay JavaScript to requestthe encrypted payment data from Apple.2. Apple uses the Secure Element to create a payment token (the PKPaymentToken structure)and encrypt the token’s payment data (the paymentData field of the PKPaymentTokenstructure) before it sends your application using the onpaymentauthorized callback function.3. You forward the encrypted payment data to your order management system to decrypt. Forinformation on decryption, see: TokenJSON.html#//apple ref/doc/uid/TP40014929-CH8-SW14. Using the Cybersource API, you submit the authorization request and include the decryptedpayment data.5. Cybersource forwards the information to the payment network, which includes your processorand the relevant payment card company.Important: You must use the Business Center or one of the Cybersource API servicesto capture, credit, or void the authorization. Refer to the Credit Card Services guide (seeRelated information below) for information.Related informationCredit Card Services guide on the Payment Services Credit Card Services pageConfiguring Your Apple Pay RequirementsRefer to https://developer.apple.com/develop for details about configuring your requirements.1. Register your merchant ID.If you are currently processing In-App transactions, you can use the same merchant ID forprocessing web transactions.2. Create or upload a Certificate Signing Request (CSR), which is used to encrypt the paymentinformation during the payment process.If you are using the merchant decryption method, generate a new CSR.If you are using the Cybersource decryption method, upload the CSR that you created in theBusiness Center when you enrolled in Apple Pay.If you are currently processing In-App transactions, you can use the same CSR for processingweb transactions.3. Register your domain. Registration is required in order to use Apple Pay on your website.4. Create a Merchant Identity Certificate. This certificate is required in order to connect to theApple servers.After configuring your Apple Pay requirements, you can set up any optional features (refer to theAuthorizations with Payment Network Tokens guides).Apple Pay - Apple Pay Integrations 14

Related informationAuthorizations with Payment Network Tokens guides (available on the Payment Services CreditCard Services page)Enrolling in Apple Pay (on page 7)Generating a New CSR (on page 8)Apple Pay - Apple Pay Integrations 15

Setting Up Apple Pay JavaScriptPreparing to use Apple Pay JavaScript to accept payments on your website involves several stagesof development. This section is an overview of those stages. For detailed instructions, follow thereferences to the Apple developer site. Enabling the Apple Pay JavaScript API: before you can display an Apple Pay button on yourwebsite or create an Apple Pay session, you need to ensure that the Apple Pay JavaScript API isenabled on your device. See Enabling the Apple Pay JavaScript API (on page 17). Displaying the Apple Pay button: Use the CSS templates provided by Apple to display theApple Pay button on your website. For more informa