Transcription
Apple PayREST APIElavon AmericasDeveloper Guide
2022. 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, the Cybersource logo, and 3-D Secure are the registered trademarks of Visa International inthe United States and other countries. All other trademarks, service marks, registered marks, or registered service marksare the property of their respective owners.Version: 22.04Apple Pay 2
ContentsRecent Revisions to This Document. 5About This Guide. 8Introduction to Apple Pay. 9Requirements for Using Apple Pay.9Supported Card Types and Optional Features.10Apple Pay Integrations. 10In-App Transactions Using the Cybersource API and Decryption.11In-App Transactions Using the Cybersource API and Merchant Decryption. 12Web Transactions Using Cybersource Decryption. 13Web Transactions Using Merchant Decryption. 14Enroll in Apple Pay.15Enrolling in Apple Pay Using the Business Center. 15Generating a New CSR Using the Business Center.16Configure Your Website to Support Apple Pay Transactions.17Configuring Apple Pay. 17Process Apple Pay Transactions. 18Authorization Service.18Authorizations Using Cybersource Decryption for American Express.18Authorizations Using Cybersource Decryption for Discover. 22Authorizations Using Cybersource Decryption for JCB.26Authorizations Using Cybersource Decryption for Mastercard.29Authorizations Using Cybersource Decryption for Visa. 33Authorizations Using Merchant Decryption for American Express.37Authorizations Using Merchant Decryption for Discover. 41Authorizations Using Merchant Decryption for JCB.44Authorizations Using Merchant Decryption for Mastercard.48Authorizations Using Merchant Decryption for Visa. 52Follow-on Services. 56Authorization Reversals. 56Captures.59Sales.64Search for Apple Pay Transactions.71Apple Pay Contents 3
Contents 4Search for Transactions. 71Transaction Search Methods.72Search Toolbar Tips. 73Use Filters and Parameters in Searches. 73Available Search Filters and Parameters.74Edit the Transaction Table Format.76Save Transaction Searches.77Apply Saved and Default Searches. 78Export Transaction Search Results. 78Search for Similar Transactions. 79Search by Transaction Phase.79Settle Transactions. 81Hide Transactions. 81Void Transactions.81Apple Pay Contents 4
Recent Revisions to This Document22.04Apple Pay Web Configuration22.03This release contains editorial revisions to the Configuring Apple Pay (on page 17)section.This revision contains only editorial changes and no technical updates.22.02ECI Field in an Authorization Request Using Merchant DecryptionCorrected the description of the API request dicator for a JCB card or Visacard transaction. See these topics: Required Fields for Authorizing a Payment Using Merchant Decryption for JCB(on page 44)22.01 Required Fields for Authorizing a Payment Using Merchant Decryption for Visa(on page 52)Added 3-D Secure support for authorization using merchant decryption:For American Express card transactions, see Required Fields for Authorizing aPayment Using Merchant Decryption for American Express (on page 37).For Discover card transactions, see Required Fields for Authorizing a Payment UsingMerchant Decryption for Discover (on page 41).For JCB card transactions, see Required Fields for Authorizing a Payment UsingMerchant Decryption for JCB (on page 44).For Mastercard transactions, see Required Fields for Authorizing a Payment UsingMerchant Decryption for Mastercard (on page 48).For Visa card transactions, see Required Fields for Authorizing a Payment UsingMerchant Decryption for Visa (on page 52).Apple Pay Recent Revisions to This Document 5
Authorization serviceAdded lists of required fields for all authorizations.Added procedures for requesting all authorizations.See Authorization Service (on page 18).Follow-on servicesAdded descriptions, required fields, procedures, and code examples for theauthorization reversal, capture, and sale services. See Follow-on Services (on page56)Apple Pay transactionsAdded section about obtaining information about Apple Pay transactions using theBusiness Center. See Process Apple Pay Transactions (on page 18)Updated links and made editorial updates to Apple Pay JavaScript API procedures.General updates21.05Updated links for external and internal references. General updates to feature namesand descriptors preferred by industry. This revision contains only editorial changesand no technical updates.Created a REST API version of this guide.21.04Changed the name of the merchantInformation.merchant.url field tomerchantInformation.merchantDomainName. See the API Field Reference for the REST API.21.03Added the tokenInformation.networkTokenOption field. See the API Field Reference for the RESTAPI.21.02Updated the card type field. See the API Field Reference for the REST API.Apple Pay Recent Revisions to This Document 6
21.01Added the field. See the API Field Reference for the REST API.Apple Pay Recent Revisions to This Document 7
About This GuideThis section describes the audience and purpose of this guide as well as conventions and relateddocumentation. See below for information about how to use this guide and where to find furtherinformation.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 8
Introduction to Apple PayRequirements 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 localCybersource sales representative. A merchant account with a supported processor (on page 10). 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 upfor Apple Pay only when these statements are true: Your processor supports payment network tokens. Cybersource supports payment network tokens with your processor.If one of these statements is not true, you must take one of these actions before you can sign upfor Apple Pay: Obtain a new merchant account with a processor that supports payment network tokens. Wait until your processor supports payment network tokens.Apple Pay Introduction to Apple Pay 9
Supported Card Types and Optional FeaturesMerchant-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 Optional Features Supplement guide.ProcessorCard TypesElavon Americas American Express Discover JCB Mastercard VisaOptional Features Merchant-initiatedtransactions Multiple partialcaptures Recurring paymentsRelated informationPayment Network Tokenization for the REST APIApple Pay IntegrationsYou can integrate Apple Pay into your payment system using these methods for In-App and Webtransactions: Cybersource Decryption Merchant DecryptionApple Pay Introduction to Apple Pay 10
In-App Transactions Using the Cybersource API and Decryption1. 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 and encrypt the token’s payment databefore it sends your application.The payment token is the PKPaymentToken structure.The payment data is the paymentData field of the PKPaymentToken structure.3. You forward the encrypted payment data to your order management system.4. Using the Cybersource API, you submit the authorization request. In thepaymentInformaton.fluidData.value field, include the Base64-encoded value obtained fromthe paymentData 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 GuidesApple Pay Introduction to Apple Pay 11
In-App Transactions Using the Cybersource API and MerchantDecryption1. 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 and encrypt the token’s payment databefore it sends your application.The payment token is the PKPaymentToken structure.The payment data is the paymentData field of the PKPaymentToken structure.3. You forward the encrypted payment data to your order management system to decrypt. Forinformation on decryption, mentTokenJSON.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 GuidesApple Pay Introduction to Apple Pay 12
Web Transactions Using Cybersource Decryption1. 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 and encrypt the token’s payment databefore it sends your application using the onpaymentauthorized callback function.The payment token is the PKPaymentToken structure.The payment data is the paymentData field of the PKPaymentToken structure.3. You forward the encrypted payment data to your order management system.4. Using the Cybersource API, you submit the authorization request. In thepaymentInformaton.fluidData.value field, include the Base64-encoded value obtained fromthe paymentData 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: Use the Business Center or one of the Cybersource API services to capture,credit, or void the authorization. Refer to the Credit Card Services guide (see Relatedinformation below) for information.Related informationCredit Card Services GuidesApple Pay Introduction to Apple Pay 13
Web Transactions Using Merchant Decryption1. 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 and encrypt the token’s payment databefore it sends your application using the onpaymentauthorized callback function.The payment token is the PKPaymentToken structure.The payment data is the paymentData field of the PKPaymentToken structure.3. You forward the encrypted payment data to your order management system to decrypt. Forinformation on decryption, mentTokenJSON.html#//apple ref/doc/uid/TP40014929-CH8-SW14. Using the Cybersource API, you submit the authorization request and include the decryptedpayment data. See Using the Merchant Decryption Method.5. Cybersource forwards the information to the payment network, which includes your processorand the relevant payment card company.Important: Use the Business Center or one of the Cybersource API services to capture,credit, or void the authorization. Refer to the Credit Card Services guide (see Relatedinformation below) for information.Related informationCredit Card Services GuidesApple Pay Introduction to Apple Pay 14
Enroll in Apple PayUse the Cybersource Business Center to enroll in Apple Pay.Enrolling in Apple Pay Using the Business CenterFollow these steps to enroll in Apple Pay using the Business Center:1. Log in to the Business Center: Test:https://businesscentertest.cybersource.com . 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: In-App: apple pay/setting up apple pay requirements Website: https://developer.apple.com/documentation/apple pay on the web/configuring your environment11. Test your software by following the steps in Requesting the Authorization Service.Apple Pay Enroll in Apple Pay 15
Important: If you are using a Cybersource test account, you must connect tothe Apple sandbox tester account and not to the Apple production system: ing/.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 or website.12. Repeat Steps 1 through 11 with your Cybersource production account and the Appleproduction account.Generating a New CSR Using the Business CenterFollow these steps to generate a new CSR using the Business Center:1. Log in to the Business Center: Test:https://businesscentertest.cybersource.com . 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.Apple Pay Enroll in Apple Pay 16
Configure Your Website to Support Apple PayTransactionsThis section describes the basic configuration tasks to configure Apple Pay on your website. To fullycomplete these tasks, you will go to the Apple Developer Center.Configuring Apple PayAfter enrolling in Apple Pay, use these steps to configure Apple Pay on your website:1. Configure Apple Pay by following the instructions on the Apple Developer pple pay on the web2. After the payment token is received, finalize the transaction by decrypting the payment databased on the type of encryption: Cybersource Decryption: This method forwards the encrypted payment data to yourorder management system. You use the Cybersource API to submit the authorizationrequest and include the Base64-encoded value obtained from the paymentData object inthe paymentInformaton.fluidData.value field.For example:session.onpaymentauthorized function (event) {var paymentDataString r paymentDataBase64 btoa(paymentDataString);} Merchant Decryption: This method forwards the encrypted payment data to yourorder management system to decrypt. For information on decryption, see PaymentToken Format Reference for details. Use the Cybersource API to submit the authorizationrequest and include the decrypted payment data.Apple Pay Configure Your Website to Support Apple Pay Transactions 17
Process Apple Pay TransactionsThis section provides information about these Apple Pay transactions: Authorizing a Payment Reversing an Authorization Capturing a Payment Authorizing and Capturing a Payment (bundled authorization and capture)Authorization ServiceYou can request the authorization service using these decryption methods: Cybersource decryption method Merchant decryption methodThis section provides the steps for requesting the authorization service using these methods, whichdetermine the request fields that are required to request the authorization service. In addition,different request fields are required to request the authorization service depending on the type ofcard used to process the transaction.Authorizations Using Cybersource Decryption for American ExpressRequired Fields for Authorizing a Payment Using Cybersource Decryption forAmerican formation.billTo.countryApple Pay Process Apple Pay Transactions 18
ntInformation.fluidData.descriptorSet this field to formaton.fluidData.valueSet this field to the Base64-encoded value obtained from the paymentData property ofthe PKPaymentToken object.processingInformation.paymentSolutionSet this field to 001Related informationAPI Field Reference for the REST APIAuthorizing a Payment Using Cybersource Decryption for American ExpressFollow these steps to authorize a payment using Cybersource decryption for American Express:1. Send the service request to:https://api.cybersource.com/pts/v2/payments2. Check the response message to make sure that the request was successful. A 200-level HTTPresponse code indicates success. For information about response codes, see TransactionResponse Codes.Apple Pay Process Apple Pay Transactions 19
Example: Cybersource Decryption and American ExpressRequest{"clientReferenceInformation": {"code": "1234567890"},"processingInformation": {"paymentSolution": "001"},"paymentInformation": {"fluidData": {"value" ,"descriptor": ng": "Base64",},"tokenizedCard": {"type": "003","transactionType": "1",}},"orderInformation": {"amountDetails": {"totalAmount": "100.00","currency": "USD"},"billTo": {"firstName": "Maya","lastName": "Lee","address1": "123 Main St","locality": "SomeCity","administrativeArea": "CA","postalCode": "94404","country": "US","email": "maya.lee@email.world","phoneNumber": "6504327113"}}}Apple Pay Process Apple Pay Transactions 20
Response{" links": {"authReversal": {"method": "POST","href": "},"self": {"method": "GET","href": e": {"method": "POST","href": }},"clientReferenceInformation": {"code": "1234567890"},"id": "6234236182176225003004","orderInformation": {"amountDetails": {"authorizedAmount": "100.00","currency": "USD"}},"paymentInformation": {"tokenizedCard": {"expirationYear": "2031","prefix": "593056","expirationMonth": "12","suffix": "0842","type": "003"},"card": {"type": "003"}},"pointOfSaleInformation": {"terminalId": "111111"},"processingInformation": {"paymentSolution": "001"},"processorInformation": {"approvalCode": "888888","networkTransactionId": "123456789619999",Apple Pay Process Apple Pay Transactions 21
"transactionId": "123456789619999","responseCode": "100","avs": {"code": "X","codeRaw": "I1"}},"reconciliationId": "75729760OPN67ZFV","status": "AUTHORIZED","submitTimeUtc": "2021-06-11T15:00:18Z"}Authorizations Using Cybersource Decryption for DiscoverRequired Fields for Authorizing a Payment Using Cybersource Decryption .expirationYearpaymentInformation.card.numberApple Pay Process Apple Pay Transactions 22
idData.descriptorSet this field to formaton.fluidData.valueSet this field to the Base64-encoded value obtained from the paymentData property ofthe PKPaymentToken object.processingInformation.paymentSolutionSet this field to eSet this field to 1.Related informationAPI Field Reference for the REST APIAuthorizing a Payment Using Cybersource Decryption for DiscoverFollow these steps to authorize a payment using Cybersource decryption for Discover:1. Send the service request to:https://api.cybersource.com/pts/v2/payments2. Check the response message to make sure that the request was successful. A 200-level HTTPresponse code indicates success. For information about response codes, see TransactionResponse Codes.Example: Cybersource Decryption and DiscoverRequest{"clientReferenceInformation": {"code": "1234567890"},"processingInformation": {"paymentSolution": "001"},"paymentInformation": {Apple Pay Process Apple Pay Transactions 23
"fluidData": {"value" ,"descriptor": "RklEPUNPTU1PTi5BUFBM
Elavon Americas American Express Discover JCB Mastercard Visa Merchant-initiated transactions Multiple partial captures Recurring payments Related information Payment Network Tokenization for the REST API Apple Pay Integrations You can integrate Apple Pay into your payment system using these methods for In-App .
