Recurring Billing. Using the Simple Order API. April CyberSource Corporation HQ P.O. Box 8999 San Francisco, CA Phone:

Transcription

1 Title Page Recurring Billing Using the Simple Order API April 2017 CyberSource Corporation HQ P.O. Box 8999 San Francisco, CA Phone:

2 CyberSource Contact Information For general information about our company, products, and services, go to For sales questions about any CyberSource Service, or call or (toll free in the United States). For support information about any CyberSource Service, visit the Support Center at Copyright 2017 CyberSource Corporation. All rights reserved. CyberSource Corporation ("CyberSource") furnishes this document and the software described in this document under the applicable agreement between the reader of this document ("You") and CyberSource ("Agreement"). You may use this document and/or software only in accordance with the terms of the Agreement. Except as expressly set forth in the Agreement, the information contained in this document is subject to change without notice and therefore should not be interpreted in any way as a guarantee or warranty by CyberSource. CyberSource assumes no responsibility or liability for any errors that may appear in this document. The copyrighted software that accompanies this document is licensed to You for use only in strict accordance with the Agreement. You should read the Agreement carefully before using the software. Except as permitted by the Agreement, You may not reproduce any part of this document, store this document 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 Legends For Government or defense agencies. Use, duplication, or disclosure by the Government or defense agencies is subject to restrictions as set forth the Rights in Technical Data and Computer Software clause at DFARS 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 and the limitations set forth in CyberSource Corporation's standard commercial agreement for this software. Unpublished rights reserved under the copyright laws of the United States. Trademarks Authorize.Net, echeck.net, and The Power of Payment are registered trademarks of CyberSource Corporation. CyberSource, CyberSource Payment Manager, CyberSource Risk Manager, CyberSource Decision Manager, and CyberSource Connect are trademarks and/or service marks of CyberSource Corporation. All other brands and product names are trademarks or registered trademarks of their respective owners. 2

3 Contents CONTENTS Recent Revisions to This Document 7 About This Guide 8 Audience and Purpose 8 Conventions 8 Note, Important, and Warning Statements 8 Text and Command Conventions 9 Related Documents 9 Customer Support 10 Chapter 1 Introduction 11 Terminology 11 Recurring Billing 11 Subscription ID 11 Secure Acceptance 12 Payment Token 12 Customer Subscriptions 12 Installment Subscription 12 Recurring Subscription 13 On-Demand Customer Profile 13 Supported Processors and Payment Methods 14 Types of Authorizations 16 Authorization Consents 17 Authorization for Electronic Checks 17 Reporting 17 Subscription Detail Report 17 Subscription Payment Exception Report 17 Transaction Endpoints 18 Test Card Numbers 18 Recurring Billing Using the Simple Order API April

4 Contents Chapter 2 Validating a Subscription 19 Charging a Setup Fee 19 Automatically Preauthorizing an Account 19 Manually Preauthorizing a Subscription 21 PINless Debit Validation 22 Chapter 3 Creating an Installment Subscription 23 Credit Card 23 Payment Network Token 24 echeck 26 PINless Debit 27 Chapter 4 Creating a Recurring Subscription 29 Credit Card 29 Payment Network Token 30 echeck 32 PINless Debit 33 Chapter 5 Retrieving Subscription Details 34 Chapter 6 Updating a Subscription 35 Card 35 Updating Card Account Number 35 Removing Card Expiration Date 36 Payment Network Token 37 Replacing Card Information with a Payment Network Token 37 Updating Payment Network Token Information 38 Replacing a Payment Network Token with Card Information 39 echeck 40 Updating an echeck Account Number 40 Changing the Payment Method 41 Updating Subscription Payments 42 Chapter 7 On-Demand Transactions 43 Requesting an On-Demand Transaction 43 Recurring Billing Using the Simple Order API April

5 Contents Converting a Transaction to a Customer Subscription 44 Chapter 8 Cancelling or Deleting a Subscription 46 Cancelling a Subscription 46 Deleting a Subscription 47 Chapter 9 Additional Features 48 Notifications 48 Format 49 Smart Tags 49 Templates 50 Successful Payment Template 50 Failed Payment Template 50 Payment Exceptions 51 Subscription Payment Exception Report 51 Retry Mode 51 Corrective Action (On Hold) 51 Optional Data Storage 52 Visa Bill Payment Program 53 Replacement Expiration Dates 54 Customer Subscription Sharing 54 Account Updater 55 Appendix A API Fields 56 Data Type Definitions 56 Relaxed Requirements for Address Data and Expiration Date 56 Numbered Elements 58 Request Fields 59 Reply Fields 76 Reason Codes 85 AVS and CVN Codes 88 International AVS Codes 88 U.S. Domestic AVS Codes 88 CVN Codes 90 Appendix B Examples 91 Name-Value Pair Examples 91 Creating a Customer Subscription 91 Recurring Billing Using the Simple Order API April

6 Contents Installment: Credit Card without a Setup Fee 91 Recurring: Credit Card with a 5.00 Setup Fee 93 Updating a Customer Subscription 94 Updating a Card Account Number 94 Removing Card Expiration Dates 95 Updating a Payment Event 95 Updating an echeck Account Number 96 Retrieving a Customer Subscription 96 Deleting a Customer Subscription 97 Cancelling a Customer Subscription 98 XML Examples 99 Creating a Customer Subscription 99 Installment: Credit Card without a Setup Fee 99 Recurring: Credit Card with a 5.00 Setup Fee 100 Updating a Customer Subscription 102 Updating a Card Account Number 102 Removing Card Expiration Dates 103 Updating an echeck Account Number 103 Retrieving a Customer Subscription 104 Deleting a Customer Subscription 105 Cancelling a Customer Subscription 106 Recurring Billing Using the Simple Order API April

7 Recent Revisions to This Document REVISIONS Release Changes April 2017 Added the Updating an echeck Account Number section. See page 40. December 2016 Added the Updating an echeck Account Number example. See page 96. Added the invoiceheader_merchantdescriptoralternate field. See page 68. June 2016 Added OmniPay Direct as a supported processor. See page 14. Renamed Global Collect to Ingenico epayments. See page 14. Updated the recurringsubscriptioninfo_numberofpayments request field. See page 73. March 2016 Added information about setting the first payment to recurring. See page 19. Updated the Removing Card Expiration Dates section. See page 36. Updated the Removing Card Expiration Dates example. See page 95. January 2016 Added the Relaxed Requirements for Address Data and Expiration Date. See page 56. Added the Removing Card Expiration Dates section. See page 36. Added the Removing Card Expiration Dates example. See page 95. Amex Direct no longer supports 0.00 preauthorizations. Recurring Billing Using the Simple Order API April

8 About This Guide ABOUT GUIDE Audience and Purpose This guide is written for merchants who want to create customer payment subscriptions and eliminate payment data from their network to ensure that customers sensitive personal information is not compromised during a security breach. A customer s sensitive information is replaced with a unique 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. It also describes how to process an on-demand transaction using a customer subscription and how to update a payment event. Conventions Note, Important, and Warning Statements Note A Note contains helpful suggestions or references to material not contained in the document. Important An Important statement contains information essential to successfully completing a task or learning a concept. Warning A Warning contains information or instructions, which, if not heeded, can result in a security risk, irreversible loss of data, or significant cost in time or revenue or both. Recurring Billing Using the Simple Order API April

9 About This Guide Text and Command Conventions Convention Usage bold Field and service names in text; for example: Include the billto_firstname field. Items that you are instructed to act upon; for example: Click Save. Screen text XML elements. Code examples and samples. Related Documents Refer to the Support Center for complete CyberSource technical documentation: Table 1 Related Documents Subject Account Updater Business Center Description Account Updater User Guide (PDF HTML) describes how to automatically incorporate changes made to a customer s payment card data. Business Center Overview (PDF HTML) describes the features and options available within the Business Center. Credit Card Credit Card Services Using the Simple Order API (PDF HTML) describes how to integrate credit card processing into your order management system. echeck Electronic Check Services Using the Simple Order API (PDF HTML) describes how to integrate echeck processing into your order management system. Offline Transaction Submission Offline Transaction File Submission Implementation Guide (PDF HTML). Payment Tokenization Payment Tokenization Using the Simple Order API (PDF HTML) describes how to create customer profiles and process on-demand payments. Payment Network Tokenization Payment Network Tokenization Using the Simple Order API (PDF HTML) describes how to add payment network tokenization to an order management system that already uses CyberSource credit card services. PINless Debit PINless Debit Card Services Using the Simple Order API (PDF HTML) describes how to integrate PINless debit processing using the Simple Order API into your order management system. Reporting Reporting Developer Guide (PDF HTML) describes how to view and configure Business Center reports. Recurring Billing Using the Simple Order API April

10 About This Guide Table 1 Related Documents (Continued) Subject Simple Order API Getting Started with CyberSource Advanced for the Simple Order API (PDF HTML) describes how to get started using the Simple Order API. Secure Acceptance Silent Order POST Secure Acceptance Web Mobile Description Simple Order API and SOAP Toolkit API Documentation and Downloads page. Simple Order API and SOAP Toolkit API Testing Information page. Secure Acceptance Silent Order POST Development Guide (PDF HTML) describes how to create a Secure Acceptance profile and integrate seamlessly with Secure Acceptance Silent Order POST. Secure Acceptance Web/Mobile Configuration Guide (PDF HTML) describes how to create a Secure Acceptance profile and integrate seamlessly with Secure Acceptance Web/Mobile. Customer Support For support information about any CyberSource service, visit the Support Center: Recurring Billing Using the Simple Order API April

11 Introduction CHAPTER 1 Terminology Recurring Billing Recurring Billing subscriptions support installment payments (see page 12) and recurring payments (see page 13). For information about on-demand payments see Payment Tokenization Using the Simple Order API. A subscription ID, also known as a payment token (see "Secure Acceptance," page 12), which you can store on your server, is a unique identifier that cannot be reverseengineered. It is generated to replace sensitive card and billing information. Recurring Billing protects sensitive cardholder information in order to comply with industry standards and government regulations and can prevent the theft of card information in storage. The recurring billing solution is compatible with the Visa and Mastercard Account Updater service. All payment information stored with CyberSource is automatically updated by participating banks, thereby reducing payment failures. See the Account Updater User Guide (PDF HTML) for more information. Subscription ID Important Contact CyberSource Customer Support to have your account configured for a 16-digit subscription 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 Luhn mod-10 checks. This subscription ID is for card customer subscriptions. Recurring Billing Using the Simple Order API April

12 Chapter 1 Introduction 16 digit displays 99 as the two leading digits and passes Luhn mod-10 checks. If your business rules prohibit using 99 as the leading digits, you must modify your system to accept the other 16-digit subscription ID. Secure Acceptance Payment Token If you are using Secure Acceptance to process transactions, the payment token is the customer subscription ID (see page 11). The payment token identifies the card and retrieves the associated billing, shipping, and card information. Customer Subscriptions Important For information about processing on-demand payments for a customer profile, see Payment Tokenization Using the Simple Order API. There are two types of subscriptions: installment subscriptions and recurring subscriptions. A customer subscription contains specific information about a customer that you store in the CyberSource database for future billing. You can also view the customer subscription in the CyberSource Business Center. A customer subscription includes: Customer contact information, such as billing and shipping information. Customer payment information, such as card type, masked account number, and expiration date. Customer order information, such as the transaction reference number and merchant defined data fields. Installment Subscription An installment subscription allows you to charge a customer s preferred payment method on a fixed number of scheduled payments. You must specify the number of payments, the amount and frequency of each payment, and the start date for processing the payments. CyberSource creates a schedule based on this information and automatically bills the customer according to the schedule. For example, you can offer a product for and let the customer pay in three installments of See "Creating an Installment Subscription," page 23. Recurring Billing Using the Simple Order API April

13 Chapter 1 Introduction Recurring Subscription A recurring subscription allows you to charge a customer s preferred payment method on a recurring payment basis with no specific end date. You must specify the amount and frequency of each payment and the start date for processing the payments. CyberSource creates a schedule based on this information and automatically bills the customer according to the schedule. For example, you can offer an online service to which the customer subscribes and can charge a monthly fee. See "Creating a Recurring Subscription," page 29. Once you have created a customer subscription, the following tasks are available to you: Update customer subscription information (see page 35). Change the payment method of a customer subscription (see page 42). Process an on-demand transaction using the customer subscription details. You can process an authorization, credit, echeck credit, and an echeck debit (see page 43). Update subscription payment events (see page 42). Retrieve customer subscription information (see page 34). Cancel a customer subscription (see page 46). Delete a customer subscription (see page 47). Share customer subscriptions (see page 54). On-Demand Customer Profile For information about processing on-demand payments for a customer profile, see Payment Tokenization Using the Simple Order API. Recurring Billing Using the Simple Order API April

14 Chapter 1 Introduction Supported Processors and Payment Methods Each customer subscription has an associated payment method: credit card, echeck, or other. Note The other payment method enables you to store data securely in a customer subscription. This payment method is useful if you do not intend to use the customer subscription for payment transactions. See "Optional Data Storage," page 52. Important All the processors listed in the table below support automatic preauthorizations and manual preauthorizations. Unless stated otherwise, each processor in the table below supports 1.00 preauthorizations using all credit card types. Table 2 Supported Processors and Payment Methods Processor Payment Method Chase Paymentech Solutions Credit card supports 0.00 preauthorizations for Visa and Mastercard cards. CyberSource ACH Service Debit card and pre-paid card supports partial authorizations for Visa, Mastercard, American Express, Discover, and Diners Club cards. Electronic check. Replacement expiry dates are supported for Visa and Mastercard cards. See "Replacement Expiration Dates," page 54. Visa Bill Payments see page 53. Electronic check. FDC Compass Credit card supports 0.00 preauthorizations for Visa and Mastercard cards. Debit card and pre-paid card supports partial authorizations for Visa, Mastercard, American Express, and Discover cards. Replacement expiry dates are supported for Visa and Mastercard cards. See "Replacement Expiration Dates," page 54. Visa Bill Payments see page 53. Recurring Billing Using the Simple Order API April

15 Chapter 1 Introduction Table 2 Supported Processors and Payment Methods (Continued) Processor FDC Nashville Global Credit card supports 0.00 preauthorizations for Visa and Mastercard cards. Debit card and pre-paid card supports partial authorizations for Visa, Mastercard, American Express, Discover, Diners Club, and JCB (US Domestic) cards. Visa Bill Payments see page 53. FDMS Nashville Credit card supports 0.00 preauthorizations for Visa cards. Debit card and pre-paid card supports partial authorizations for Visa, Mastercard, American Express, Discover, Diners Club, and JCB (US Domestic) cards. Visa Bill Payments see page 53. FDMS South Credit card supports 0.00 preauthorizations for Visa and Mastercard cards. Debit card and pre-paid card supports partial authorizations for Visa, Mastercard, American Express, Discover, and JCB (US Domestic) cards. Replacement expiry dates are supported for Visa and Mastercard cards. See "Replacement Expiration Dates," page 54. GPN Credit card supports 0.00 preauthorizations for Visa and Mastercard cards. Moneris Debit card and pre-paid card supports partial authorizations for Visa, Mastercard, American Express, Discover, Diners Club, and JCB cards. Visa Bill Payments see page 53. Credit card supports 0.00 preauthorizations for Visa and Mastercard cards. RBS WorldPay Atlanta Credit card supports 0.00 preauthorizations for Visa and Mastercard cards. TeleCheck Payment Method Electronic check. Electronic check supports 1.00 preauthorizations. TSYS Acquiring Solutions Credit card supports 0.00 preauthorizations for Visa and Mastercard cards and 1.00 preauthorizations using American Express, Discover, Diners Club, and JCB cards. Debit card and pre-paid card supports partial authorizations for Visa, Mastercard, American Express, Discover, Diners Club, and JCB cards. Visa Bill Payments see page 53. Recurring Billing Using the Simple Order API April

16 Chapter 1 Introduction Types of Authorizations Table 3 Types of Authorizations Authorization Automatic preauthorization Manual preauthorization Automatic preauthorization reversal Partial authorization Description Automatically preauthorize a credit card when you create a customer subscription, or automatically preauthorize a bank account when you create an echeck customer subscription. See page 19. Depending on the payment method and if your account has been configured for automatic preauthorizations, CyberSource automatically runs several fraud checks during a preauthorization: AVS and CVN checks for cards, and for cards and echecks. Note Partial authorizations for prepaid cards and debit cards cannot be performed for automatic preauthorizations. Important Contact your merchant account provider to determine whether you will be charged a fee for a preauthorization. Manually preauthorize a customer s account when you create a customer subscription. This feature is available only with the CyberSource API. See page 21. Important Contact your merchant account provider to determine whether you will be charged a fee for a preauthorization. If your processor supports full authorization reversal, you can contact CyberSource Customer Support to automatically reverse preauthorizations when you create a customer subscription. CyberSource does not charge you for reversing automatic preauthorizations. If you cannot create a customer subscription for any reason, or if the preauthorization amount is 0.00, CyberSource does not reverse the automatic preauthorization. Important TSYS Acquiring Solutions does not support automatic preauthorization reversals. When the balance on a debit card or prepaid card is lower than the requested authorization amount, the issuing bank can approve a partial amount. Note Partial authorizations for prepaid cards and debit cards cannot be performed for automatic preauthorizations. Recurring Billing Using the Simple Order API April

17 Chapter 1 Introduction Authorization Consents Authorization for Electronic Checks To support customer subscriptions that use electronic checks, you must display a separate consent agreement accepted by the customer before you create the customer subscription. The authorization statement must: Be readily identifiable as an authorization. Clearly and conspicuously state its terms including the transaction amount and the effective date of the transfer. Include the routing number and bank account number to be debited. Specify the frequency of the debits and the period of time during which the customer s payment authorization is granted. Include instructions for revoking the authorization. Reporting Subscription Detail Report The Subscription Detail report is available in XML and CSV formats and provides detailed information about customer subscriptions and their transactions. You can view the report on the Business Center, or you can use a client API to programmatically download the report. For a detailed description of the Subscription Detail Report, and for details about downloading the report, see the Reporting Developer Guide (PDF HTML). Subscription Payment Exception Report The Subscription Payment Exception Report provides information about installment and recurring customer subscriptions. The report includes two lists: retry mode and on hold. See "Subscription Payment Exception Report," page 51. Recurring Billing Using the Simple Order API April

18 Chapter 1 Introduction Transaction Endpoints Important Contact CyberSource Customer Support to configure your account for Recurring Billing. For live transactions, send requests to the production server: When you use the production server, the payment method you are testing determines whether you use real card numbers or real account numbers. Create customer subscriptions that use small amounts, such as Search for and view your live customer subscriptions in the production version of the Business Center: For test transactions, send requests to the test server: Search for and view your test subscriptions in the test version of the Business Center: Test Card Numbers You may use the following test credit card numbers for transactions: Credit Card Type Test Account Number Visa Mastercard American Express Discover JCB Diners Club Maestro International (16 digits) Maestro Domestic (16 digits) Recurring Billing Using the Simple Order API April

19 Validating a Subscription CHAPTER 2 Important PINless debits cannot be preauthorized. You must validate the card before you create the customer subscription. See "PINless Debit Validation," page 22. Three validation methods are available to validate a credit card or echeck customer subscription before you create it. Charging a Setup Fee This fee can be charged only for card and echeck payments. It is a one-time optional fee that you can charge only when you are creating a customer subscription. Request the CreateService and include the setup fee in the purchasetotals_grandtotalamount field, along with the other required fields for creating a subscription. See "Credit Card," page 23. Important CyberSource recommends that you do not enable partial authorizations for authorizing a setup fee. If the issuing bank approves a partial amount for the setup fee, the customer subscription is not created. Automatically Preauthorizing an Account Only card payments and echeck payments can be preauthorized, and CyberSource does not charge you for this feature. Before the customer subscription is created, CyberSource authorizes a small amount against the payment method entered for the customer subscription. Each payment processor supports different preauthorization amounts. See "Supported Processors and Payment Methods," page 14. Recurring Billing Using the Simple Order API April

20 Chapter 2 Validating a Subscription If your account is configured for automatic preauthorizations, CyberSource automatically runs several fraud checks depending on the payment method: AVS checks credit card only CVN checks credit card only Decision Manager credit card and electronic checks If your payment processor supports full authorization reversals you can contact CyberSource Customer Support to automatically reverse preauthorizations. When you create a customer subscription with automatic preauthorizations and automatic preauthorization reversals enabled, the order of services is: 1 Credit card authorization for the preauthorization. 2 Subscription creation only if the authorization is successful. 3 Full authorization reversal only if the authorization is successful and the preauthorization amount is not To enable automatic preauthorizations using the Business Center: Step 1 Step 2 Step 3 Step 4 Log in to the Business Center: Live Transactions: Test Transactions: In the left navigation pane, choose Recurring Billing > Settings. Check Perform an automatic preauthorization before creating subscriptions. Click Submit Changes. To set the e-commerce indicator for the first payment to recurring: Step 1 Step 2 Step 3 Log in to the Business Center: Live Transactions: Test Transactions: In the left navigation pane, choose Recurring Billing > Settings. Check Set e-commerce indicator for first payment to Recurring. Recurring Billing Using the Simple Order API April

21 Chapter 2 Validating a Subscription Important All subsequent recurring payments are set to recurring regardless of this setting. This setting is for all card types on Atos and for Mastercard and American Express transactions on FDC Nashville Global. Step 4 Click Submit Changes. To disable automatic preauthorizations using the API: Note Use the CreateService_disableAutoAuth field if your CyberSource account is configured for automatic preauthorizations. Step 1 Step 2 Request the CreateService service. See "Creating a Recurring Subscription," page 29. In the CreateService request, set the CreateService_disableAutoAuth field to true. Manually Preauthorizing a Subscription This feature is available only for card payments and echeck payments. You can manually preauthorize a customer s subscription when you create it. Important If your processor (see page 14) supports full authorization reversals and if you charged more than 0.00 for the preauthorization, CyberSource recommends that you subsequently request a full authorization reversal. To manually preauthorize a card customer subscription: Step 1 Request the CreateService service. See "Credit Card," page 23. Step 2 Include the following fields in the request: ccauthservice_run set to true. purchasetotals_grandtotalamount set to 0.00 or a small amount. Recurring Billing Using the Simple Order API April

22 Chapter 2 Validating a Subscription Note For all card types on Atos and for Mastercard and American Express transactions on FDC Nashville Global, include the following fields: ccauthservice_commerceindicator=recurring To use the Business Center for setting the e-commerce indicator to recurring, see page 20. ccauthservice_firstrecurringpayment=true card_cvnumber Credit Card Services Using the Simple Order API (PDF HTML) To manually preauthorize an echeck customer subscription: Step 1 Request the CreateService service. See "echeck," page 26. Step 2 Include the following fields in the request: ecdebitservice_run set to true. ecdebitservice_paymentmode set to 1. PINless Debit Validation PINless debits cannot be preauthorized. Instead, you must validate the card before you create the customer subscription. To validate a PINless debit card you must request the pinlessdebitvalidateservice service before requesting the CreateService service. For detailed information about requesting the pinlessdebitvalidateservice service, see the PINless Debit Card Services Using the Simple Order API (PDF HTML). Recurring Billing Using the Simple Order API April

23 Creating an Installment Subscription CHAPTER 3 Credit Card Important You must validate the customer account before the customer subscription is created. See "Validating a Subscription," page 19. If you need to include a setup fee, see "Charging a Setup Fee," page 19. To create an installment subscription: Step 1 Step 2 Set the CreateService_run service field to true. Include the following fields in the request: billto_firstname billto_lastname billto_city billto_country billto_ billto_postalcode billto_state billto_street1 card_accountnumber card_cardtype card_expirationmonth card_expirationyear merchantid merchantreferencecode purchasetotals_currency recurringsubscriptioninfo_frequency recurringsubscriptioninfo_amount recurringsubscriptioninfo_startdate recurringsubscriptioninfo_numberofpayments Recurring Billing Using the Simple Order API April

24 Chapter 3 Creating an Installment Subscription See "API Fields," page 56, for detailed descriptions of the request and reply fields. See Example 1, page 91 for a request and reply example. Payment Network Token Note You can request an authorization before requesting that a subscription be created. For the authorization request details, see Payment Network Tokenization Using the Simple Order API (PDF HTML). To create an installment subscription: Step 1 Set the CreateService_run service field to true. Set the ccauthservice_run service field to true. For Visa cards include the following payer authentication fields: ccauthservice_commerceindicator=vbv ccauthservice_cavv=the cryptogram value ccauthservice_xid=the cryptogram value For Mastercard cards include the following payer authentication fields: ccauthservice_commerceindicator=spa ccauthservice_cavv=the cryptogram value ucaf_collectionindicator=2 For American Express cards include the following payer authentication fields: ccauthservice_commerceindicator=aesk ccauthservice_cavv=block A of the cryptogram value. If it is a 20-byte cryptogram, include it in this field. ccauthservice_xid=block B of the cryptogram value. If it is a 40-byte cryptogram, include the first 20-byte value (block A) in the ccauthservice_cavv field and the second 20-byte value (block B) in this field. Recurring Billing Using the Simple Order API April

25 Chapter 3 Creating an Installment Subscription Step 2 Include the following fields in the request: billto_firstname billto_lastname billto_city billto_country billto_ billto_postalcode billto_state billto_street1 card_accountnumber populate with the network token value obtained from your payment network token provider. card_cardtype must be 001, 002, or 003. card_expirationmonth populate with the network token expiration month obtained from payment network token provider. card_expirationyear populate with the network token expiration year obtained from payment network token provider. merchantid merchantreferencecode purchasetotals_currency recurringsubscriptioninfo_frequency recurringsubscriptioninfo_amount recurringsubscriptioninfo_startdate recurringsubscriptioninfo_numberofpayments paymentnetworktoken_transactiontype set to 1. paymentnetworktoken_requestorid this field is supported only for CyberSource through VisaNet. See "API Fields," page 56, for detailed descriptions of the request and reply fields. Recurring Billing Using the Simple Order API April

26 Chapter 3 Creating an Installment Subscription echeck Important You must validate the customer account before the customer subscription is created. See "Validating a Subscription," page 19. To create a customer subscription that uses echecks: Step 1 Step 2 Set the CreateService_run service field to true. Include the following fields in the request: subscription_paymentmethod set to check. billto_firstname billto_lastname billto_city billto_country billto_ billto_postalcode billto_state billto_street1 billto_phonenumber contact your payment processor representative to learn whether this field is required or optional. merchantid merchantreferencecode purchasetotals_currency recurringsubscriptioninfo_frequency recurringsubscriptioninfo_amount recurringsubscriptioninfo_startdate recurringsubscriptioninfo_numberofpayments billto_dateofbirth billto_driverslicensenumber contact your TeleCheck representative to learn whether this field is required or optional. billto_driverslicensestate contact your TeleCheck representative to learn whether this field is required or optional. billto_companytaxid contact your TeleCheck representative to learn whether this field s required or optional. check_accountnumber check_accounttype check_banktransitnumber Recurring Billing Using the Simple Order API April

27 Chapter 3 Creating an Installment Subscription check_seccode required if your processor is TeleCheck. check_checknumber contact your payment processor representative to learn whether this field is required or optional. See "API Fields," page 56, for detailed descriptions of the request and reply fields. PINless Debit Important You must validate the customer account before the customer subscription is created. See "PINless Debit Validation," page 22. To create a customer subscription that uses PINless debits: Step 1 Step 2 Set the UpdateService_run service field to true. Include the following fields in the request: subscription_paymentmethod set to pinless debit. billto_firstname billto_lastname billto_city billto_country billto_ billto_postalcode billto_state billto_street1 card_accountnumber card_expirationmonth card_expirationyear merchantid merchantreferencecode purchasetotals_currency recurringsubscriptioninfo_frequency recurringsubscriptioninfo_amount recurringsubscriptioninfo_startdate recurringsubscriptioninfo_numberofpayments Recurring Billing Using the Simple Order API April

28 Chapter 3 Creating an Installment Subscription See "API Fields," page 56, for detailed descriptions of the request and reply fields. Recurring Billing Using the Simple Order API April

29 Creating a Recurring Subscription CHAPTER 4 Credit Card Important You must validate the customer account before the customer subscription is created. See "Validating a Subscription," page 19. If you need to include a setup fee, see "Charging a Setup Fee," page 19. To create a recurring subscription: Step 1 Step 2 Step 3 Step 4 Set the CreateService_run service field to true Set the ccauthservice_run service field to true authorizes the setup fee. Set the cccaptureservice_run service field to true captures the setup fee. Include the following fields in the request: billto_firstname billto_lastname billto_city billto_country billto_ billto_postalcode billto_state billto_street1 card_accountnumber card_cardtype card_expirationmonth card_expirationyear merchantid merchantreferencecode purchasetotals_currency recurringsubscriptioninfo_frequency Recurring Billing Using the Simple Order API April

30 Chapter 4 Creating a Recurring Subscription recurringsubscriptioninfo_amount recurringsubscriptioninfo_startdate See "API Fields," page 56, for detailed descriptions of the request and reply fields. See Example 3, page 93 for a request and reply example. Payment Network Token Note You can request an authorization before requesting that a subscription be created. For the authorization request details, see Payment Network Tokenization Using the Simple Order API (PDF HTML). To create a recurring subscription: Step 1 Set the CreateService_run service field to true. Set the ccauthservice_run service field to true. For Visa cards include the following payer authentication fields: ccauthservice_commerceindicator=vbv ccauthservice_cavv=the cryptogram value ccauthservice_xid=the cryptogram value For Mastercard cards include the following payer authentication fields: ccauthservice_commerceindicator=spa ccauthservice_cavv=the cryptogram value ucaf_collectionindicator=2 For American Express cards include the following payer authentication fields: ccauthservice_commerceindicator=aesk ccauthservice_cavv=block A of the cryptogram value. If it is a 20-byte cryptogram, include it in this field. ccauthservice_xid=block B of the cryptogram value. If it is a 40-byte cryptogram, include the first 20-byte value (block A) in the ccauthservice_cavv field and the second 20-byte value (block B) in this field. Step 2 Include the following fields in the request: billto_firstname billto_lastname billto_city Recurring Billing Using the Simple Order API April

31 Chapter 4 Creating a Recurring Subscription billto_country billto_ billto_postalcode billto_state billto_street1 card_accountnumber populate with the network token value obtained from your payment network token provider. card_cardtype must be 001, 002, or 003. card_expirationmonth populate with the network token expiration month obtained from payment network token provider. card_expirationyear populate with the network token expiration year obtained from payment network token provider. merchantid merchantreferencecode purchasetotals_currency recurringsubscriptioninfo_frequency recurringsubscriptioninfo_amount recurringsubscriptioninfo_startdate paymentnetworktoken_transactiontype set to 1. paymentnetworktoken_requestorid this field is supported only for CyberSource through VisaNet. See "API Fields," page 56, for detailed descriptions of the request and reply fields. Recurring Billing Using the Simple Order API April

32 Chapter 4 Creating a Recurring Subscription echeck Important You must validate the customer account before the customer subscription is created. See "Validating a Subscription," page 19. To create a recurring subscription that uses echecks: Step 1 Step 2 Set the CreateService_run service field to true. Include the following fields in the request: subscription_paymentmethod set to check. billto_firstname billto_lastname billto_city billto_country billto_ billto_postalcode billto_state billto_street1 billto_phonenumber contact your payment processor representative to learn whether this field is required or optional. merchantid merchantreferencecode purchasetotals_currency recurringsubscriptioninfo_frequency billto_dateofbirth billto_driverslicensenumber contact your TeleCheck representative to learn whether this field is required or optional. billto_driverslicensestate contact your TeleCheck representative to learn whether this field is required or optional. billto_companytaxid contact your TeleCheck representative to learn whether this field is required or optional. check_accountnumber check_accounttype check_banktransitnumber check_seccode required if your processor is TeleCheck. check_checknumber contact your payment processor representative to learn whether this field is required or optional. Recurring Billing Using the Simple Order API April

33 Chapter 4 Creating a Recurring Subscription See "API Fields," page 56, for detailed descriptions of the request and reply fields. PINless Debit Important You must validate the customer account before the customer subscription is created. See "PINless Debit Validation," page 22. To create a recurring subscription that uses PINless debits: Step 1 Step 2 Set the UpdateService_run service field to true. Include the following fields in the request: subscription_paymentmethod set to pinless debit. billto_firstname billto_lastname billto_city billto_country billto_ billto_postalcode billto_state billto_street1 card_accountnumber card_expirationmonth card_expirationyear merchantid merchantreferencecode purchasetotals_currency recurringsubscriptioninfo_frequency See "API Fields," page 56, for detailed descriptions of the request and reply fields. Recurring Billing Using the Simple Order API April

34 Retrieving Subscription Details CHAPTER 5 To retrieve a subscription details: Step 1 Step 2 Set the RetrieveService_run service field to true. Include the following fields in the request: merchantid merchantreferencecode recurringsubscriptioninfo_subscriptionid See "API Fields," page 56, for detailed descriptions of the request and reply fields. See Example 13, page 96 for a request and reply example. Recurring Billing Using the Simple Order API April

35 Updating a Subscription CHAPTER 6 Card Updating Card Account Number Important You can update all fields except the recurringsubscriptioninfo_frequency, recurringsubscriptioninfo_startdate and recurringsubscriptioninfo_ numberofpaymentsfields. In the example below, the customer s card account number is updated. Note If your account is configured to use a 16 digit format-preserving subscription ID (see page 11), and you update the card number, you receive a new subscription ID if the last four digits of the new card number are different from the previous card number. The status of the previous subscription ID changes to superseded. You cannot update, delete, or cancel a customer subscription that has a status of superseded. To update a customer s card account number: Note When you update the card number for a customer subscription, CyberSource recommends that you validate the customer subscription. See "Validating a Subscription," page 19. Step 1 Step 2 Set the UpdateService_run service field to true. Include the following fields in the request: card_accountnumber card_cardtype card_expirationmonth this field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See page 56. Recurring Billing Using the Simple Order API April

36 Chapter 6 Updating a Subscription card_expirationyear this field is optional if your CyberSource account is configured for relaxed requirements for address data and expiration date. See page 56. merchantid merchantreferencecode recurringsubscriptioninfo_subscriptionid See, "API Fields," page 56, for detailed descriptions of the request and reply fields. See Example 5, page 94 for a request and reply example. Removing Card Expiration Date To remove a customer s card expiration date: Step 1 Step 2 Set the UpdateService_run service field to true. Include the following fields in the request: card_expirationmonth set to 0. card_expirationyear set to 0. merchantid merchantreferencecode recurringsubscriptioninfo_subscriptionid See "API Fields," page 56, for detailed descriptions of the request and reply fields. See Example 7, page 95 for a request and reply example. Recurring Billing Using the Simple Order API April

37 Chapter 6 Updating a Subscription Payment Network Token Replacing Card Information with a Payment Network Token You can replace the customer s card information, which is stored in the customer subscription, with a payment network token. For more information about payment network tokens, see page 12. Note Updated billing and shipping information can also be included in the request. To remove a value that is stored in the customer subscription, include the relevant API field in the request, but do not include a value for the field. To replace a customer s card information with a payment network token: Step 1 Step 2 Set the UpdateService_run service field to true. Include the following fields in the request: card_accountnumber populate with the network token value obtained from your payment network token provider. card_cardtype must be 001, 002, or 003. card_expirationmonth populate with the network token expiration month obtained from your payment network token provider. card_expirationyear populate with the network token expiration year obtained from your payment network token provider. paymentnetworktoken_transactiontype set to 1. paymentnetworktoken_requestorid this field is supported only for CyberSource through VisaNet. merchantid merchantreferencecode recurringsubscriptioninfo_subscriptionid See "API Fields," page 56, for detailed descriptions of the request and reply fields. Recurring Billing Using the Simple Order API April

38 Chapter 6 Updating a Subscription Updating Payment Network Token Information You can update the payment network token information that is stored in the customer subscription. For more information about payment network tokens, see page 12. Note Updated billing and shipping information can also be included in the request. To remove a value that is stored in the customer subscription, include the relevant API field in the request, but do not include a value for the field. To update a customer s payment network token: Step 1 Step 2 Set the UpdateService_run service field to true. Include the following fields in the request: card_accountnumber populate with the network token value obtained from your payment network token provider. card_cardtype must be 001, 002, or 003. card_expirationmonth populate with the network token expiration month obtained from your payment network token provider. card_expirationyear populate with the network token expiration year obtained from your payment network token provider. paymentnetworktoken_transactiontype set to 1. paymentnetworktoken_requestorid this field is supported only for CyberSource through VisaNet. merchantid merchantreferencecode recurringsubscriptioninfo_subscriptionid See "API Fields," page 56, for detailed descriptions of the request and reply fields. Recurring Billing Using the Simple Order API April

39 Chapter 6 Updating a Subscription Replacing a Payment Network Token with Card Information You can replace the customer s payment network token, which is stored in the customer subscription, with the customer s card information. For more information about payment network tokens, see page 12. Note Updated billing and shipping information can also be included in the request. To remove a value that is stored in the customer subscription, include the relevant API field in the request, but do not include a value for the field. To update a customer s payment network token to card information: Step 1 Step 2 Set the UpdateService_run service field to true. Include the following fields in the request: card_accountnumber card_cardtype card_expirationmonth card_expirationyear paymentnetworktoken_transactiontype include an empty value in this field. paymentnetworktoken_requestorid include an empty value in this field. merchantid merchantreferencecode recurringsubscriptioninfo_subscriptionid See "API Fields," page 56, for detailed descriptions of the request and reply fields. Recurring Billing Using the Simple Order API April

40 Chapter 6 Updating a Subscription echeck Updating an echeck Account Number Important You can also update the routing number by including the new value in the check_banktransitnumber field as part of the update request. To update an echeck account number: Step 1 Step 2 Set the UpdateService_run service field to true. Include the following fields in the request: check_accountnumber merchantid merchantreferencecode recurringsubscriptioninfo_subscriptionid See "API Fields," page 56, for detailed descriptions of the request and reply fields. See Example 11, page 96 for a request and reply example. Recurring Billing Using the Simple Order API April

41 Chapter 6 Updating a Subscription Changing the Payment Method Important You must validate the customer account before the customer subscription is created. See "Validating a Subscription," page 19. Note You cannot change the payment method to or from the Other payment method. The Other payment method enables you to store data securely in a customer subscription. This payment method is useful if you do not intend to use the customer subscription for payment transactions. See Payment Tokenization Using the Simple Order API. To change the payment method of a customer subscription: Step 1 Step 2 Set the UpdateService_run service field to true. Include the following fields in the request: subscription_paymentmethod change to credit card, or check, or pinless debit. merchantid merchantreferencecode recurringsubscriptioninfo_subscriptionid See "API Fields," page 56, for detailed descriptions of the request and reply fields. Recurring Billing Using the Simple Order API April