Transcription
Title PageToken Management ServiceUsing the Simple Order API
Cybersource Contact InformationFor general information about our company, products, and services, go to http://www.cybersource.com.For sales questions about any Cybersource service, email sales@cybersource.com or call 650-432-7350 or 888330-2300 (toll free in the United States).For support information about any Cybersource service, visit the Support Center:http://www.cybersource.com/supportCopyright 2020. Cybersource Corporation. All rights reserved. Cybersource Corporation ("Cybersource") furnishes thisdocument and the software described in this document under the applicable agreement between the reader ofthis document ("You") and Cybersource ("Agreement"). You may use this document and/or software only inaccordance with the terms of the Agreement. Except as expressly set forth in the Agreement, the informationcontained in this document is subject to change without notice and therefore should not be interpreted in any wayas a guarantee or warranty by Cybersource. Cybersource assumes no responsibility or liability for any errors thatmay appear in this document. The copyrighted software that accompanies this document is licensed to You foruse 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 thisdocument in a retrieval system, or transmit this document, in any form or by any means, electronic, mechanical,recording, or otherwise, without the prior written consent of Cybersource.Restricted Rights LegendsFor Government or defense agencies: Use, duplication, or disclosure by the Government or defense agenciesis subject to restrictions as set forth the Rights in Technical Data and Computer Software clause at DFARS252.227-7013 and in similar clauses 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 setforth in Cybersource Corporation's standard commercial agreement for this software. Unpublished rightsreserved under the copyright laws of the 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 theUnited States and other countries. All other trademarks, service marks, registered marks, or registered servicemarks are the property of their respective owners.Revision: December 20202
CONTENTSContentsRecent Revisions to This DocumentAbout This Guide6Audience and Purpose6Conventions 6Text and Command ConventionsRelated DocumentsCustomer SupportChapter 1Introduction6778Token Types and FormatsRequirements5911Transaction Endpoints11Supported Processors and Payment Methods12Relaxed Requirements for Address Data and Expiration DateMerchant-Initiated Transactions14Automatically Preauthorizing an AccountChapter 2Creating Customer Tokens1516Creating a Customer Token for a Payment Card16Authorize and Create a Customer Token for a Payment CardCreating a Customer Token for an Electronic CheckRetrieving a Customer TokenUpdating a Customer TokenDeleting a Customer Token141718192021Requesting On-Demand Transactions22Token Management Service Using the Simple Order API 3
ContentsChapter 3Creating Credentials-on-File Network TokensRequirements24Creating a COF Network TokenTesting232425COF Network Token NotificationsAppendix A API Fields27Data Type DefinitionsRequest FieldsReply FieldsAppendix B ExamplesAppendix C Card Types252728384554Appendix D Reason Codes56Token Management Service Using the Simple Order API 4
ReleaseChangesDecember 2020Added support for the processor Cielo 3.0. See "Supported Processors andPayment Methods," page 12, and ccAuthService overridePaymentMethod,page 31.REVISIONSRecent Revisions to ThisDocumentChanged Cybersource through VisaNet to Visa Platform Connect.Removed support for PINless debit cards.Moneris: added support for China UnionPay cards.June 2020Added an endpoint for transactions in India. See "Transaction Endpoints,"page 11.May 2020Updated information about retrieving a customer token. See "Retrieving aCustomer Token," page 19.Added the on-demand credit procedure. See "Requesting On-DemandTransactions," page 22.Added a notification example for card enrollment. See Example 1, "PANEnrollment Notification," on page 25.Updated the paymentAccountReference reply field. SeepaymentAccountReference, page 38.Updated "Reply: Retrieve a Customer Token," page 51.March 2020This revision contains only editorial changes and no technical updates.February 2020Updated the description for payment instrument tokens. See Paymentinstrument token, page 10.Updated the URL for information about merchant-initiated transactions. See"Merchant-Initiated Transactions," page 14.November 2019Visa Platform Connect: added support for COF network tokens forMastercard. See "Creating Credentials-on-File Network Tokens," page 23.Token Management Service Using the Simple Order API 5
ABOUT GUIDEAbout This GuideAudience and PurposeThis guide is written for merchants who want to tokenize customers’ sensitive personalinformation and eliminate payment data from their networks to ensure that it is notcompromised.The purpose of this guide is to help you create and manage tokens.ConventionsA Note contains helpful suggestions or references to material not contained inthe document.An Important statement contains information essential to successfullycompleting a task or learning a concept.Text and Command ConventionsConventionUsageBold Field and service names in text; for example:Include the paySubscriptionCreateService run field. Items that you are instructed to act upon; for example:Click Save.Screen text XML elements. Code examples and samples. Text that you enter in an API environment; for example:Set the paySubscriptionCreateService run field to true.Token Management Service Using the Simple Order API 6
About This GuideRelated DocumentsTable 1Related DocumentsSubjectDescriptionAccount UpdaterAccount Updater User Guide (PDF HTML)—describes how toautomatically incorporate changes made to a customer’spayment card data.Business CenterBusiness Center Reporting User Guide (PDF HTML)—describes reporting options you can use to download yourtransaction data.Credit CardCredit Card Services Using the Simple Order API (PDF HTML)—describes how to integrate credit card processing intoyour order management system.EcheckElectronic Check Services Using the Simple Order API (PDF HTML)—describes how to integrate Echeck processing into yourorder management system.PayoutsPayouts Using the Simple Order API (PDF HTML)—describeshow to integrate Payouts processing into your ordermanagement system.Simple Order API Getting Started with Cybersource Advanced for the SimpleOrder API (PDF HTML)—describes how to get started usingthe Simple Order API. Simple Order API and SOAP Toolkit API Testing Informationpage.Refer to the Support Center for complete Cybersource technical documentation:http://www.cybersource.com/support center/support documentationCustomer SupportFor support information about any Cybersource service, visit the Support Center:http://www.cybersource.com/supportToken Management Service Using the Simple Order API 7
CHAPTERIntroduction1Contact Cybersource Customer Support to configure your account for theToken Management Service.The Cybersource Token Management Service (TMS) tokenizes, securely stores, andmanages: Primary account number (PAN) Payment card expiration date Customer data Electronic check dataTMS is compatible with the Cybersource Account Updater service for Visa and Mastercardpayment cards, except with credentials-on-file (COF) network tokens. All paymentinformation stored with Cybersource can be automatically updated by participating banks,thereby reducing payment failures. For more information, see Account Updater UserGuide (PDF HTML).Token Management Service Using the Simple Order API 8
Chapter 1IntroductionToken Types and FormatsAll token types are also available using the TMS RESTful services. For more informationabout RESTful services, see the Cybersource Developer Center.Table 2Token Types and FormatsToken TypeDescriptionFormatCustomer tokenPayment Card Transactions and PayoutsRepresents the tokenized: 32 characterhexadecimal (default) 19 digits, Luhn checkpassing 16 digits, last 4 digitsof card preserving,Luhn check passing1 16 digits, Luhn checkpassing1For moreinformation, seeChapter 2, "CreatingCustomer Tokens,"on page 16. Payment card PAN Card expiration date Billing information Shipping information Merchant-defined data Electronic ChecksRepresents the tokenized: Bank account and routing numbers Billing information Shipping information Driver license information Account type Company tax ID SEC code Alternate merchant descriptor Merchant-defined data22 digits2 (Request ID) 32 characterhexadecimal (default) 19 digits, Luhn checkpassing 16 digits, Luhn checkpassing1 22 digits21Token format for existing merchants who implemented Cybersource services prior to 2019.2Can be used only for one token type—customer, payment instrument, or instrument identifier. Forinstrument identifier tokens, you can use the 22-digit format for payment cards and electronic checks.Token Management Service Using the Simple Order API 9
Chapter 1Table 2IntroductionToken Types and Formats (Continued)Token TypeDescriptionFormatPayment instrumenttokenAvailable only with TMS RESTful services. For more information oncreating this token using TMS RESTful services, see CybersourceDeveloper Center.Payment Card Transactions and PayoutsRepresents the tokenized: Payment card PAN Card expiration date Billing informationElectronic ChecksRepresents the tokenized:Instrument identifiertoken Bank account and routing numbers Billing information Driver license information Account type Company tax ID SEC code Alternate merchant descriptor 32 characterhexadecimal 19 digits, Luhn checkpassing 16 digits, Luhn checkpassing 22 digits2Helps you identify when the same card or bank account is used whilekeeping sensitive customer data secure.Payment Card Transactions and PayoutsRepresents the tokenized payment cardPAN. 32 characterhexadecimal 19 digits, Luhn checkpassing 19 digits, last 4 digitsof card preserving(default) 16 digits, Luhn checkpassing Electronic ChecksRepresents the tokenized bank account androuting numbers.22 digits2 32 characterhexadecimal 19 digits, Luhn checkpassing 16 digits, Luhn checkpassing 22 digits21Token format for existing merchants who implemented Cybersource services prior to 2019.2Can be used only for one token type—customer, payment instrument, or instrument identifier. Forinstrument identifier tokens, you can use the 22-digit format for payment cards and electronic checks.Token Management Service Using the Simple Order API 10
Chapter 1IntroductionMultiple merchant IDs can be configured for various token types. You receivethe instrument identifier token regardless of your account’s token type.Reasons for multiple merchant IDs include: You have multiple processors. Point-of-sale terminals have unique merchant IDs, which are usuallyconfigured for the PAN-only instrument identifier token.When you have multiple merchant IDs, you can set up one token vault to whichall of your merchant IDs have access or set up multiple vaults to segregateaccess to tokens. See "Token Types and Formats," page 9.RequirementsYou must: Have a merchant account with a supported processor. Create a Cybersource account:https://www.cybersource.com/register/ Contact Cybersource Customer Support to enable your account for the TokenManagement Service and o enable relaxed requirements for address data andexpiration date settings. You must confirm the token type and format that you want touse, as described in Table 2, "Token Types and Formats." Install a Cybersource Simple Order API client or the SOAP Toolkit. Use Simple OrderAPI 1.135 or later.Transaction EndpointsFor live transactions, send requests to the production ctionProcessorFor live transactions in India, send requests to the production server in actionProcessorFor test transactions, send requests to the test ansactionProcessorToken Management Service Using the Simple Order API 11
Chapter 1IntroductionSupported Processors and PaymentMethodsThe processors listed in Table 3 support customer and instrument identifier tokens, unlessnoted otherwise.Table 3Supported Processors and Payment MethodsProcessorPayment MethodsAIBMSCredit card.American Express BrightonCredit card.Important Does not support automatic preauthorizationreversals.American Express DirectDebit card and prepaid card.Asia-Mideast ProcessingCredit card.BarclaysCredit card—supports 0.00 preauthorizations for Visa andMastercard.Chase Paymentech Solutions Credit card—supports 0.00 preauthorizations for Visa andMastercard. Debit card and prepaid card—supports partialauthorizations for Visa, Mastercard, American Express,Discover, and Diners Club. Electronic check. Credit card—supports 0.00 preauthorizations using Visa,Mastercard, American Express, Discover, Diners Club, JCB,Hipercard, Aura, and Elo. Debit card—authorization request must includeccAuthService overridePaymentMethod set to DB.Cielo 3.0CitibankCredit card—supports 0.00 preauthorizations for Visa andMastercard.Comercio LatinoCredit card—supports 1.00 preauthorizations using Visa,Mastercard, American Express, Discover, Diners Club, JCB,Hipercard, Aura, and Elo.Credit Mutuel-CIC Credit card—supports 0.00 preauthorizations using Visa,Mastercard, and Cartes Bancaires. Debit card and prepaid card.Cybersource ACH ServiceElectronic check.Elavon AmericasCredit card—supports 0.00 preauthorizations using Visa,Mastercard, American Express, Discover, Diners Club, andChina UnionPay.FDC Compass Credit card—supports 0.00 preauthorizations for Visa andMastercard. Debit card and prepaid card. Payouts.Token Management Service Using the Simple Order API 12
Chapter 1Table 3IntroductionSupported Processors and Payment Methods (Continued)ProcessorPayment MethodsFDC Nashville Global Credit card—supports 0.00 preauthorizations for Visa andMastercard. Debit card and prepaid card. Credit card—supports 0.00 preauthorizations for Visa. Debit card and prepaid card. Credit card—supports 0.00 preauthorizations for Visa andMastercard. Debit card and prepaid card.GPN Credit card—supports 0.00 preauthorizations for Visa andMastercard. Debit card and prepaid card.HSBCCredit card—supports 0.00 preauthorizations for Visa andMastercard.FDMS NashvilleFDMS SouthImportant Does not support automatic preauthorizationreversals.Ingenico ePaymentsCredit card.JCN GatewayCredit card.LloydsTSB CardnetCredit card.MonerisCredit card—supports 0.00 preauthorizations for Visa,Mastercard, and China UnionPay.OmniPay DirectCredit card—supports 0.00 preauthorizations using Visa,Mastercard, Maestro (International), and Maestro (UKDomestic).OmniPay-IrelandCredit card—supports 0.00 preauthorizations using Visa andMastercard.RBS WorldPay Atlanta Credit card—supports 0.00 preauthorizations for Visa andMastercard. Electronic check.StreamlineCredit card—supports 0.00 preauthorizations for Visa andMastercard.SIXCredit card.TeleCheckElectronic check—supports 1.00 preauthorizations.TSYS Acquiring Solutions Credit card—supports 0.00 preauthorizations for Visa andMastercard cards and 1.00 preauthorizations usingAmerican Express, Discover, Diners Club, and JCB. Debit card and prepaid card.Visa Platform Connect Visa Platform Connect waspreviously called Cybersourcethrough VisaNet.Credit card—supports 0.00 preauthorizations for Visa andMastercard. Credit card—supports 1.00 preauthorizations for AmericanExpress, Discover, Diners Club, and JCB. Debit card and prepaid card. Payouts.Token Management Service Using the Simple Order API 13
Chapter 1Table 3IntroductionSupported Processors and Payment Methods (Continued)ProcessorPayment MethodsWorldpay VAP Credit card—supports 0.00 preauthorizations for AmericanExpress, Diners Club, Discover, JCB, Mastercard, and Visa. Debit card and prepaid card.Worldpay VAP was previouslycalled Litle. Litle waspurchased by Vantiv, whichwas then purchased byWorldpay VAP. If you have anyquestions about this situation,contact your account managerat Worldpay VAP.Relaxed Requirements for Address Dataand Expiration DateTo enable relaxed requirements for address data and expiration date, contactCybersource Customer Support to have your account configured for this feature. Fordetails about relaxed requirements, see the Relaxed Requirements for Address Data andExpiration Date page.Merchant-Initiated TransactionsTMS simplifies compliance with mandates for merchant-initiated transactions andcredentials-on-file. This helps you to achieve higher authorization success rates. Forinformation about merchant-initiated transactions, ial-on-File-for-Visa-Mastercard-and-DiscoverToken Management Service Using the Simple Order API 14
Chapter 1IntroductionAutomatically Preauthorizing an AccountCybersource can automatically verify that a payment card or electronic check account isvalid prior to tokenization by authorizing a zero or low value amount, depending on thecard type. See "Supported Processors and Payment Methods," page 12. There is noadditional charge from Cybersource for this service.If your account is configured for automatic preauthorizations, Cybersource automaticallyruns several fraud checks during a preauthorization depending on the payment method forthe new customer profile: AVS checks—credit card only CVN checks—credit card only Decision Manager—credit card and electronic checksIf your payment processor supports full authorization reversals, you can contactCybersource Customer Support to automatically reverse preauthorizations. When youcreate a customer profile with automatic preauthorizations and automatic preauthorizationreversals enabled, the order of services is:1Credit card authorization service for the preauthorization.2Subscription create service—only if the authorization is successful.3Full authorization reversal service—only if the authorization is successful and thepreauthorization amount is not 0.00.You can disable the automatic preauthorization for an individual token create or updaterequest using the paySubscriptionCreateService disableAutoAuth field. SeeAppendix A, "API Fields," on page 27.Token Management Service Using the Simple Order API 15
CHAPTERCreating Customer Tokens2The customer token represents customer-related information including details for apayment card or electronic check, billing address, shipping address, and merchantdefined data. For a description of all token types, see "Token Types and Formats," page 9.You can configure your merchant ID to request an automatic account verification (alsoknown as a 0.0 or 1.00 preauthorization) when you create a token. If the verification fails,the token is not created. Contact Cybersource Customer Support to enable this for yourmerchant ID. See "Authorize and Create a Customer Token for a Payment Card,"page 17.The customer token is returned in the paySubscriptionCreateReply subscriptionIDfield. The instrument identifier token is also returned in thepaySubscriptionCreate
Simple Order API and SOAP Toolkit API Testing Information page. CHAPTER Token Management Service Using the Simple Order API 8 Introduction 1 The Cybersource Token Management Service (TMS) tokenizes, securely stores, and manages:
