Transcription
Recurring BillingSimple Order APIDeveloper 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.02Recurring Billing 2
ContentsRecent Revisions to This Document. 7About This Guide. 8Introduction to Recurring Billing.11Subscription ID. 11Payment Network Token. 12Secure Acceptance. 12Customer Subscriptions. 12Installment Subscriptions.12Recurring Subscriptions.13On-Demand Customer Profile.13Supported Processors and Payment Methods. 13Relaxed Requirements for Address Data and Expiration Date.17Types of Authorizations.18Authorization Consents.19Authorization for Electronic Checks.19Reporting. 20Subscription Detail Report. 20Transaction Endpoints.20Test Card Numbers.21Validating a Subscription. 22Charging a Setup Fee.22Automatically Preauthorizing an Account. 22Enable Automatic Preauthorizations Using the Business Center. 23Set the e-commerce Indicator for the First Payment to Recurring. 23Disable Automatic Preauthorizations Using the API.24Manually Preauthorizing a Subscription.24Manually Preauthorize a Card Customer Subscription. 24Manually Preauthorize an eCheck Customer Subscription. 25Creating an On-Demand Customer Profile.26Credit Card without a Setup Fee.26Create a Customer a Profile Without a Setup Fee. 26Credit Card with a Setup Fee.27Recurring Billing Contents 3
Contents 4Create a Customer Profile with a 5.00 Setup Fee. 27Payment Network Token. 28Create a Customer Profile Including the Payment Network Token.28eCheck. 29Create an eCheck Customer Profile. 29Creating an Installment Subscription.31Credit Card. 31Create an Installment Subscription. 31Payment Network Token. 32Create an Installment Subscription. 32eCheck. 33Create a Customer Subscription.33Creating a Recurring Subscription. 35Credit Card. 35Create a Recurring Subscription. 35Payment Network Token. 36Create a Recurring Subscription. 36eCheck. 37Create a Recurring Subscription. 37Retrieving Subscription Details. 39Retrieve Subscription Details. 39Updating a Subscription. 40Payment Card.40Updating Payment Card Account Number.40Removing Payment Card Expiration Date.41Payment Network Token. 41Replacing Payment Card Information with a Payment Network Token.41Updating Payment Network Token Information.42Replacing a Payment Network Token with Payment Card Information.43eCheck. 44Updating an Echeck Account Number.44Changing the Payment Method.44Change the Payment Method of a Customer Subscription. 44Update Subscription Payments.45On-Demand Transactions.46Recurring Billing Contents 4
Contents 5Requesting an On-Demand Transaction.46Request an On-demand Sale Transaction. 46Request an On-demand Credit Transaction. 46Converting a Transaction to a Customer Subscription. 47Convert a Transaction to A Customer Subscription. 47Canceling or Deleting a Subscription.48Cancel a Customer Subscription. 48Delete a Customer Subscription.48Additional Features. 49Email Notifications. 49Configure Email Notifications.49Email Format.50Email Smart Tags.50Email Templates.51Merchant-Initiated Transactions.52Payment Exceptions.52Optional Data Storage.52Visa Bill Payment Program.53Replacement Expiration Dates.53Customer Subscription Sharing.54Account Updater.55API Fields. 56Data Type Definitions. 56Numbered Elements. 56Service Names. 57Simple Order API Request Fields. 58Simple Order API Response Fields. 81Reason Codes. 91AVS and CVN Codes. 95International AVS Codes. 96U.S. Domestic AVS Codes.96CVN Codes. 98Simple Order API Examples.100Name-Value Pair Examples.100Recurring Billing Contents 5
Contents 6Creating a Customer Profile without a Setup Fee.100Creating a Customer Profile with a 5.00 Setup Fee. 101Creating a Customer Subscription. 102Updating a Customer Subscription.104Retrieving a Customer Subscription. 106Deleting a Customer Subscription. 107Canceling a Customer Subscription. 107XML Examples. 108Creating a Customer Profile without a Setup Fee.108Creating a Customer Profile with a 5.00 Setup Fee. 109Creating a Customer Subscription. 111Updating a Customer Subscription.113Retrieving a Customer Subscription. 116Deleting a Customer Subscription. 117Canceling a Customer Subscription. 117Recurring Billing Contents 6
Recent Revisions to This DocumentReleaseChanges22.02Updated the Business Center URLs.21.01Added maximum number of retries to Payment Exceptions(on page 52).22.0120.02Updated the request fieldpaymentNetworkToken transactionType to includevalues 2 and 3. See Simple Order API Request Fields (onpage 58).Changed Cybersource through VisaNet to Visa PlatformConnect.Removed support for PINless debit cards.20.0119.04Moneris: added support for China UnionPay. SeeSupported Processors and Payment Methods (on page13).Added endpoints and Business Center URLs for India.Updated Business Center procedures throughout.Added Creating an On-Demand Customer Profile (on page26).Updated creating an installment customer profile with apayment network token. See Payment Network Token (onpage 32).19.03Updated creating a recurring customer profile with apayment network token. See Payment Network Token (onpage 36).Added JCN Gateway as a supported processor. SeeSupported Processors and Payment Methods (on page13).Recurring Billing Recent Revisions to This Document 7
About This GuideAudience and PurposeThis guide is written for merchants who want to create customer payment subscriptions andeliminate payment data from their network to ensure that customers’ sensitive personal informationis not compromised during a security breach. A customer’s sensitive information is replaced with aunique identifier, known as a subscription ID, which you store on your network.The purpose of this guide is to help you create, update, retrieve, and delete customer subscriptions. Italso describes how to process an on-demand transaction using a customer subscription and how toupdate a payment event.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 DocumentationRelated DocumentsSubjectDescriptionAccount UpdaterAccount Updater User Guide—describes howto automatically incorporate changes made to acustomer’s payment card data.Authorizations withPayment NetworkTokensCredit Card ServicesAuthorizations with Payment Network TokensUsing the Simple Order API—describes how torequest authorizations with payment networktokens.Credit Card Services Developer Guide—describeshow to integrate credit card processing into yourorder management system.Recurring Billing About This Guide 8
Related Documents (continued)SubjectDescriptionElectronic CheckServicesElectronic Check Services Developer Guide for theSimple Order API—describes how to integrateecheck processing into your order managementsystem.Offline TransactionSubmissionReportingSecure AcceptanceCheckout APISecure AcceptanceHosted CheckoutSimple Order APIOffline Transaction File Submission ImplementationGuide.Business Center Reporting User Guide— describesthe features and options available in the BusinessCenter.Secure Acceptance Checkout API Integration Guide—describes how to create a Secure Acceptanceprofile and integrate seamlessly with SecureAcceptance Checkout API.Secure Acceptance Hosted Checkout IntegrationGuide —describes how to create a SecureAcceptance profile and integrate seamlessly withSecure Acceptance Hosted Checkout. Getting Started with Cybersource Essentials—describes how to get started using theSimple Order API. Simple Order API and SOAP Toolkit APIDocumentation and Downloads page. Simple Order API and SOAP Toolkit APITesting Information page.For additional documentation, visit these documentation sites: Cybersource Developer Center/Developer Guides: ides.html Cybersource Support Center/Technical Documentation: l-documentation.html Cybersource Technical Documentation Portal: https://docs.cybersource.com/en/index.htmlCustomer SupportFor support information about any service, visit the Support Center:Recurring Billing About This Guide 9
http://www.cybersource.com/supportRecurring Billing About This Guide 10
Introduction to Recurring BillingRecurring Billing protects sensitive cardholder information in order to comply with industrystandards and government regulations and can prevent the theft of payment card information. TheRecurring Billing solution is compatible with the Visa and Mastercard Account Updater service. Allpayment information stored with Cybersource is automatically updated by participating banks,thereby reducing payment failures. See the Account Updater User Guide for more information.Recurring Billing can be used only to collect scheduled payments from customers, not to disbursepayments.Contact customer support to configure your account for Recurring Billing.Subscription IDA subscription ID, also known as a payment token, which you can store on your server, is a uniqueidentifier that cannot be reverse-engineered. It replaces sensitive payment card and billinginformation.Important: Contact customer support to have your account configured for a 16-digitsubscription ID, or to update from a 22-digit subscription ID to a 16-digit subscription ID.There are three types of subscription IDs: 22 digit—the default subscription ID. 16 digit—displays the final 4 digits of the primary account number (PAN) and passes Luhnmod-10 checks. This subscription ID is for payment card customer subscriptions. 16 digit—displays 99 as the two leading digits and passes Luhn mod-10 checks. If yourbusiness rules prohibit using 99 as the leading digits, you must modify your system to acceptthe other 16-digit subscription ID.Recurring Billing Introduction to Recurring Billing 11
Payment Network TokenThe payment network token replaces the primary account number (PAN) that is stored in a customersubscription. You can create a customer subscription and include the payment network token (seePayment Network Token (on page 32)), update the payment network token details (see UpdateSubscription Payments (on page 45)), and replace a payment network token with updatedpayment card details (see Changing the Payment Method (on page 44)).Secure AcceptanceIf you use Secure Acceptance to process transactions, the payment token is the customersubscription ID (see Subscription ID (on page 11)). The payment token identifies the paymentcard and retrieves the associated billing, shipping, and payment card information.Customer SubscriptionsThere are two types of subscriptions: installment subscriptions and recurring subscriptions. Acustomer subscription contains specific information about a customer that you store in the databasefor future billing. You can also view the customer subscription in the Business Center.A customer subscription includes but is not limited to: Billing and shipping information. Payment card type, masked account number, and expiration date. Transaction reference numbers and merchant-defined data fields.Installment SubscriptionsAn installment subscription enables you to charge a customer’s preferred payment method on afixed number of scheduled payments. You must specify the number of payments, the amount andfrequency of each payment, and the start date for processing the payments. Cybersource creates aschedule based on this information and automatically bills the customer according to the schedule.For example, you can offer a product for 75.00 and let the customer pay in three installments of25.00.See Creating an Installment Subscription (on page 31).Recurring Billing Introduction to Recurring Billing 12
Recurring SubscriptionsA recurring subscription allows you to charge a customer’s preferred payment method on a recurringpayment basis with no specific end date. You must specify the amount and frequency of eachpayment and the start date for processing the payments. Cybersource creates a schedule based onthis information and automatically bills the customer according to the schedule. For example, youcan offer an online service to which the customer subscribes and can charge a monthly fee.After you have created a customer subscription, you can: Update customer subscription information. Change the payment method of a customer subscription. Process an on-demand transaction using the customer subscription details. Update subscription payment events. Retrieve customer subscription information. Cancel a customer subscription. Delete a customer subscription. Share customer subscriptions (see Customer Subscription Sharing (on page 54)).See Creating an Installment Subscription (on page 31).On-Demand Customer ProfileFor information about processing on-demand payments to create a customer profile, see Creating anOn-Demand Customer Profile (on page 26).Supported Processors and Payment MethodsEach customer subscription has an associated payment method: credit card, echeck, or other.The other payment method enables you to store data securely in a customer subscription. Thispayment method is useful if you do not intend to use the customer subscription for paymenttransactions. See Optional Data Storage (on page 52).All the processors listed in the table below support automatic preauthorizations and manualpreauthorizations. Unle
Secure Acceptance If you use Secure Acceptance to process transactions, the payment token is the customer subscription ID (see Subscription ID (on page 11)). The payment token identifies the payment card and retrieves the associated billing, shipping, and payment card information.
