CyberSource Global Payment Service

Transcription

1 Title Page CyberSource Global Payment Service Developer Guide For Bank Transfers, Brazilian Boletos Bancários, and Direct Debits Simple Order API SCMP API March 2015 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 2015 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 CyberSource, The Power of Payment, CyberSource Payment Manager, CyberSource Risk Manager, CyberSource Decision Manager, CyberSource Connect, Authorize.Net, and echeck.net 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 8 About This Guide 10 Audience and Purpose 10 Conventions 10 Note and Important Statements 10 Text and Command Conventions 10 Related Documents 11 Customer Support 11 Chapter 1 Getting Started 12 Global Collect 12 Bank Account Requirements 12 API Versions for the XML Schema 12 Order Tracking 13 Reconciliation IDs and Transaction Reference Numbers 13 Request IDs 14 Payment Reference Numbers 14 Chapter 2 Bank Transfers and Bank Transfer Refunds Using the Simple Order API 15 Requesting Bank Transfers 15 Requesting Bank Transfer Refunds 16 Researching a Missing Payment 17 API Fields 18 Request Fields 18 Reply Fields 25 Request and Reply Examples 28 Bank Transfer Request 28 Bank Transfer Reply 29 Standalone Bank Transfer Refund Request 30 Standalone Bank Transfer Refund Reply 31 Global Payment Service Developer Guide March

4 Contents Follow-On Bank Transfer Refund Request 31 Follow-On Bank Transfer Refund Reply 32 Chapter 3 Bank Transfers and Bank Transfer Refunds Using the SCMP API 33 Requesting Bank Transfers 33 Requesting Bank Transfer Refunds 34 Researching a Missing Payment 35 API Fields 36 Request Fields 36 Offer-Level Fields 41 Reply Fields 42 Reply Flags 45 Request and Reply Examples 46 Bank Transfer Request 46 Bank Transfer Reply 47 Standalone Bank Transfer Refund Request 48 Standalone Bank Transfer Refund Reply 49 Follow-On Bank Transfer Refund Request 49 Follow-On Bank Transfer Refund Reply 50 Chapter 4 Real-Time Bank Transfers Using the Simple Order API 51 Transaction Status 51 Sending the Query 51 Viewing the Response 53 Requesting Real-Time Bank Transfers 54 Requesting Real-Time Bank Transfer Refunds 55 API Fields 55 Request Fields 55 Bank Codes 60 Reply Fields 61 Additional Request Fields 63 Request and Reply Examples 64 Real-Time Bank Transfer Request 64 Real-Time Bank Transfer Reply 65 Real-Time Bank Transfer Refund 65 Real-Time Bank Transfer Refund Reply 66 Global Payment Service Developer Guide March

5 Contents Chapter 5 Real-Time Bank Transfers Using the SCMP API 67 Transaction Status 67 Sending the Query 67 Viewing the Response 69 Requesting Real-Time Bank Transfers 70 Requesting Real-Time Bank Transfer Refunds 71 API Fields 71 Request Fields 71 Offer-Level Fields 75 Bank Codes 76 Reply Fields 78 Reply Flags 79 Additional Request Fields 80 Request and Reply Examples 81 Real-Time Bank Transfer Request 81 Real-Time Bank Transfer Reply 81 Real-Time Bank Transfer Refund Request 82 Real-Time Bank Transfer Refund Reply 83 Chapter 6 Boletos Bancários Using the Simple Order API 84 Requesting a Boleto Bancário 84 API Fields 84 Data Type Definitions 84 Request Fields 85 Reply Fields 86 Examples 88 Name-Value Pairs: Request 88 Name-Value Pairs: Reply 88 XML: Request 89 XML: Reply 89 Chapter 7 Boletos Bancários Using the SCMP API 90 Requesting a Boleto Bancário 90 API Fields 90 Request Fields 90 Reply Fields 92 Reply Flags 94 Request and Reply Examples 95 Request 95 Reply 95 Global Payment Service Developer Guide March

6 Contents Chapter 8 Reports for Boletos Bancários 96 Boleto Bancário Unfulfilled Report 96 Viewing and Downloading Reports 96 XML Conventions and Data Types 97 Syntax for Report Declarations 97 Syntax for Element Declarations 98 Data Types and Lengths 98 Elements in the Report 99 <Report> 99 <Summary> 101 <Range> 103 <TransactionDetail> 104 <Transaction> 105 DTD 108 Example 109 Single Transaction Report 112 Chapter 9 Direct Debits and Direct Debit Refunds Using the Simple Order API 115 Requesting Direct Debits 115 Requesting Direct Debit Refunds 116 API Fields 118 Request Fields 118 Reply Fields 126 Request and Reply Examples 128 Direct Debit Request 128 Direct Debit Reply 129 Standalone Direct Debit Refund Request 129 Follow-On Direct Debit Refund 130 Chapter 10 Direct Debits and Direct Debit Refunds Using the SCMP API 132 Requesting Direct Debits 132 Requesting Direct Debit Refunds 133 API Fields 135 Request Fields 135 Offer-Level Fields 141 Reply Fields 142 Reply Flags 144 Request and Reply Examples 145 Direct Debit Request 145 Direct Debit Refund Standalone 147 Direct Debit Refund Follow-On 148 Global Payment Service Developer Guide March

7 Contents Chapter 11 Testing 149 Sending Test Requests 149 Testing Bank Transfers, Direct Debits, and Refunds 149 Testing Real-Time Bank Transfers 151 Testing Your CyberSource Interface 151 Testing Your Network Interface 152 Going Live 153 Appendix A Product Codes 154 Appendix B Reason Codes 155 Reason Codes for the Simple Order API 155 Appendix C Researching a Missing Bank Transfer Payment 158 Index 161 Global Payment Service Developer Guide March

8 Recent Revisions to This Document REVISIONS Release Changes March 2015 Updated Example 15. See page 54. Updated Example 22. See page 70. January 2015 December 2014 Removed the Interac processor from the document. Removed requirement to send request token fields with follow-on bank transfer and direct debit refunds. See the following sections: Bank transfers: Simple Order API "Requesting Bank Transfer Refunds," page 16 SCMP API "Requesting Bank Transfer Refunds," page 34 Direct debits: Simple Order API "Requesting Direct Debit Refunds," page 116 SCMP API "Requesting Direct Debit Refunds," page 133 Updated customer company API request field length specifications and added shipping name and phone number API request fields to the following tables: Bank transfers: Simple Order API Table 5, page 18 SCMP API Table 7, page 36 Real-time bank transfers: Simple Order API Table 12, page 55 SCMP API Table 17, page 71 Updated the response examples for Simple Order API real-time bank transfer payments. See "Viewing the Response," page 53. Added the request token API reply field to the following tables: Real-time bank transfers: Simple Order API Table 14, page 61 SCMP API Table 20, page 78 Added the bank SWIFT code information to the following sections: Direct debits: Simple Order API "Requesting Direct Debits," page 115, Table 37, page 118, and Example 41, page 128 SCMP API "Requesting Direct Debits," page 132, Table 39, page 135, Example 47, page 145, and Example 49, page 147 Global Payment Service Developer Guide March

9 Recent Revisions to This Document Release September 2014 August 2014 Changes This revision contains only editorial changes and no technical updates. Removed the following request fields for direct debits and direct debit refunds: directdebitservice_mandateid direct_debit_mandate_id July 2014 Added examples to the following sections: Bank transfers Simple Order API page 28. SCMP API page 46. Real-time bank transfers Simple Order API page 64. SCMP API page 81. Direct debits Simple Order API page 128. SCMP API page 145. Global Payment Service Developer Guide March

10 About This Guide ABOUT GUIDE Audience and Purpose This guide is written for merchants who want to use the Global Collect processor to offer the Global Payment services to customers. This guide describes the tasks a merchant must complete in order to make bank transfers and bank transfer refunds, real-time bank transfers, boleto bancario payments, and direct debits and direct debit refunds. Conventions Note and Important 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. Text and Command Conventions Convention Usage bold Field and service names in text; for example: Include the ics_applications field. Items that you are instructed to act upon; for example: Click Save. Global Payment Service Developer Guide March

11 About This Guide Convention Usage monospace XML elements. Code examples and samples. Text that you enter in an API environment; for example: Set the davservice_run field to true. Related Documents The Global Payment Service Planning Guide (PDF HTML) describes the business and technical implementations a merchant must complete in order to make bank transfers and bank transfer refunds, real-time bank transfers, boleto bancario payments, and direct debits and direct debit refunds. Credit Card Services Using the Simple Order API (PDF HTML) describes the tasks you must complete to integrate the credit card services into your existing management system. Credit Card Services Using the SCMP API (PDF HTML) describes the tasks you must complete to integrate the credit card services into your existing order management system. Getting Started with CyberSource Advanced for the Simple Order API (PDF HTML) describes how to get started using the Simple Order API. Getting Started with CyberSource Advanced for the SCMP API (PDF HTML) describes how to get started using the SCMP API. The Reporting Developer Guide (PDF HTML) describes how to download reports. Refer to the Support Center for complete CyberSource technical documentation: Customer Support For support information about any CyberSource service, visit the Support Center: Global Payment Service Developer Guide March

12 Getting Started CHAPTER 1 Global Collect The Global Payment Service supports the Global Collect processor. This processor supports all the countries mentioned in the Global Payment Service Planning Guide (PDF HTML) Bank Account Requirements Become familiar with the bank account requirements for the countries in which you will be processing payments. Contact CyberSource Customer Support for required countryspecific bank account information. API Versions for the XML Schema For general information about the API versions, see Getting Started with CyberSource Advanced for the Simple Order API. The following table shows which Simple Order API version to use for new payment methods. Table 1 Choosing a Simple Order API Version Payment Method Boletos Bancários Real-time bank transfers Version 1.42 or later 1.23 or later Global Payment Service Developer Guide March

13 Chapter 1 Getting Started Order Tracking For general information about order tracking, see Getting Started with CyberSource Advanced for the Simple Order API or Getting Started with CyberSource Advanced for the SCMP API. Reconciliation IDs and Transaction Reference Numbers The following table lists the field names for the reconciliation IDs and transaction reference numbers for the Global Payment Service payment methods. Table 2 Reconciliation IDs and Transaction Reference Numbers Payment Method Service Field Names Bank transfers Bank transfer Simple Order API: banktransferreply_reconciliationid SCMP API: bank_transfer_trans_ref_no Boletos Bancários Bank transfer refund Real-time bank transfer Boleto Bancário payment Simple Order API: banktransferrefundreply_reconciliationid SCMP API: bank_transfer_refund_trans_ref_no Simple Order API: banktransferrealtimereply_ reconciliationid SCMP API: bank_transfer_real_time_trans_ref_no Simple Order API: boletopaymentreply_reconciliationid SCMP API: boleto_payment_trans_ref_no Direct debits Direct debit Simple Order API: directdebitreply_reconciliationid SCMP API: direct_debit_trans_ref_no Direct debit refund Simple Order API: directdebitrefundreply_reconciliationid SCMP API: direct_debit_refund_trans_ref_no Global Payment Service Developer Guide March

14 Chapter 1 Getting Started Request IDs For all Global Payment Services, the request ID is returned in the reply message in: requestid for the Simple Order API request_id for the SCMP API The following table lists the field names for the Global Payment Service request IDs in the request messages. Table 3 Reconciliation IDs and Transaction Reference Numbers Payment Method Service Field Names Bank transfers Bank transfer refund for a bank transfer Bank transfer refund for a realtime bank transfer Simple Order API: banktransferrefundservice_banktransferrequestid SCMP API: bank_transfer_request_id Simple Order API: banktransferrefundservice_ banktransferrealtimerequestid SCMP API: bank_transfer_real_time_request_id Direct debits Direct debit refund Simple Order API: directdebitrefundservice_ directdebitrequestid SCMP API: direct_debit_request_id Payment Reference Numbers The payment reference number is a unique value for each bank transfer. CyberSource returns this value in the bank transfer reply message, and you must display it prominently to the customer. The customer must send in the number with the bank transfer so that the payment can be matched to the order. The following table lists the field names for the payment reference numbers. Table 4 Payment Reference Numbers Service Field Names Bank transfer Simple Order API: banktransferreply_paymentreference SCMP API: bank_transfer_payment_reference Real-time bank transfer Simple Order API: banktransferrealtimereply_ paymentreference SCMP API: bank_transfer_real_time_payment_reference Global Payment Service Developer Guide March

15 Bank Transfers and Bank Transfer Refunds Using the Simple Order API CHAPTER 2 Requesting Bank Transfers To request a bank transfer, set the banktransferservice_run field to true. See Table 5, page 18, for a list of the fields to use when requesting the service. When requesting a bank transfer, you may not request any other ICS service except Tax Calculation. For more information about the service, see Tax Calculation Service Using the Simple Order API. In the bank transfer reply, you receive fields containing information about the bank and bank account that the customer should transfer funds to. Display this information to customers so that they can easily transcribe it or print it and give it to their banks. The information includes the bank s name, bank s country, the account holder s name, and so on. The primary field containing the bank account information is banktransferreply_ accountnumber. This field contains the bank account number information you need to display, including a bank code or sort code, branch code or check digit, if any of those are used for the particular country. You can display the contents of the field as you receive it in the reply from CyberSource. You might also receive the banktransferreply_iban field with the International Bank Account Number (IBAN). The IBAN is an international standard for bank account numbers that the EU is adopting. In the future, the EU is planning to switch to using only the IBAN format and not the original format presented in banktransferreply_accountnumber. If the IBAN is present in the reply, display it to the customer along with the other bank information, and identify it as the IBAN. Depending on the country, you might also receive the bank s SWIFT code, which is another bank identifier. When the banktransferreply_bankswiftcode field is present, display the SWIFT code to the customer along with the other bank information, and identify it as the SWIFT code. Global Payment Service Developer Guide March

16 Chapter 2 Bank Transfers and Bank Transfer Refunds Using the Simple Order API Requesting Bank Transfer Refunds Important From August 1, 2016, for euro countries and from October 31, 2016, for noneuro countries, the IBAN must be included in each request. If you provide a BBAN it will be converted to an IBAN, and this conversion process will continue only until August 1, a Important A follow-on refund must occur within 60 days of the request for the bank transfer. After the time limit expires, only a stand-alone refund can be requested. To refund a bank transfer, wait 1 to 3 days after the bank transfer request is processed by CyberSource. When you attempt to request a followon refund before the initial bank transfer is processed into your merchant bank account, the error ORDER WITHOUT REFUNDABLE PAYMENTS is displayed. This error could also mean that your account is not configured for standalone refunds with Global Collect. To configure your account, please contact CyberSource Customer Support. There are two types of bank transfer refunds: follow-on refunds and stand-alone refunds. A follow-on refund uses information from a previous bank transfer. A stand-alone refund does not depend on a previous transaction. To request a bank transfer refund: Set the banktransferrefundservice_run field to true. Do not request any other ICS services except Tax Calculation, which is optional. For more information about this service, see Tax Calculation Service Using the Simple Order API. Send the fields required for a bank transfer refund request as described in Table 5, page 18. For a follow-on refund, the fields and values must match the fields and values you sent in the bank transfer request. For a stand-alone refund, the banktransferrefundservice_ banktransferrequestid field is optional. See page 30. For a follow-on refund, include one of these fields from the original request with the request ID (see page 31): banktransferrefundservice_banktransferrequestid banktransferrefundservice_banktransferrealtimerequestid The easiest way to implement bank transfer refunds is to always send the request ID from the original bank transfer with every bank transfer refund request. Global Payment Service Developer Guide March

17 Chapter 2 Bank Transfers and Bank Transfer Refunds Using the Simple Order API CyberSource recommends that when you request a refund, you use the same value for merchantreferencecode that you used for the bank transfer. This makes it easier for you to link the refund to the original bank transfer in your own system as well as in CyberSource reports and transaction search screens. CyberSource validates basic checks the format of the bank account number before performing the bank transfer refund. If the account number does not pass the validation, CyberSource rejects the request with reasoncode=244 instead of processing the bank transfer refund. CyberSource recommends that you then confirm that the customer entered the number correctly, and if it is incorrect, request the refund again with the correct number. You may perform multiple partial refunds against a bank transfer. The sum of the refunds may not exceed the amount of the payment. You do not receive an error in the reply for either of the following conditions: The banktransferrefundservice_banktransferrequestid field is invalid. The customer s payment has not yet been received. Instead, CyberSource does not process the refund, and the transaction appears in the daily Transaction Exception Detail Report. You should monitor this report daily for transactions problems. For descriptions of the reason codes that can appear in the report, see "Reason Codes," page 155. For information about the report and how to use it, see the Global Payment Service Planning Guide. For details about downloading the report and its format, see the Reporting Developer Guide. Researching a Missing Payment If CyberSource cannot match the customer s payment information to the information you submit in the original bank transfer request (typically because the customer made a mistake), a situation could arise in which a customer makes a bank transfer payment but does not receive the goods, and CyberSource s report and your bank account statement do not show that you received the payment. You can make a payment inquiry in the Business Center and have CyberSource research the missing payment and try to match your request with the customer s payment. Note You must wait at least five days after the funds are debited from the customer s account before initiating an inquiry because it can take that long for the funds to appear in your account and in CyberSource s reports. CyberSource does not allow you to perform an inquiry within five days of submitting the initial bank transfer request. For instructions on using the Business Center to research a lost payment, see Appendix C, "Researching a Missing Bank Transfer Payment," on page 158. Global Payment Service Developer Guide March

18 Chapter 2 Bank Transfers and Bank Transfer Refunds Using the Simple Order API API Fields For information about the data types, see Getting Started with CyberSource Advanced for the Simple Order API. Request Fields The following table lists the fields to use in requests for bank transfers and bank transfer refunds. Table 5 Request Fields for Bank Transfers and Bank Transfer Refunds for the Simple Order API Request Field Description Used By and Required (R) or Optional (O) Data Type & Length bankinfo_address Bank s address. Refund (O) String (255) bankinfo_bankcode bankinfo_branchcode bankinfo_city bankinfo_country Bank's code. Used for some countries when you are not using the IBAN. Contact CyberSource Customer Support for required country-specific bank account information. Note This is a required field if the bankinfo_country field is GB, AT, FR, or DE. For more information see the twocharacter ISO Standard Country Codes. Code that identifies the branch of the customer's bank when you are not using the IBAN. City in which the bank is located. Some banks validate the bank account information, so consider sending this field if the bank is not located in the same city of the billing address. Country in which the bank is located. Use the two-character ISO Standard Country Codes. Note If bankinfo_country is not set, CyberSource uses billto_country to determine the country in which the bank transfer is taking place. 1. Required if billto_country value is US or CA 2. Required if any shipping information is included 3. Required if shipto_country value is US or CA Refund (See String (See Refund (O) String (15) Refund (O) String (40) Bank Transfer (See Refund (R) String (2) Global Payment Service Developer Guide March

19 Chapter 2 Bank Transfers and Bank Transfer Refunds Using the Simple Order API Table 5 Request Fields for Bank Transfers and Bank Transfer Refunds for the Simple Order API (Continued) Request Field Description Used By and Required (R) or Optional (O) Data Type & Length bankinfo_name bankinfo_swiftcode banktransferrefundservice_ banktransferrequestid banktransferrefundservice_ reconciliationid banktransferrefundservice_ run banktransferservice_run Bank's name. Note This is a required field if the bankinfo_country field is AU, FI, FR, IT, NO, ES, SE, or CH. For more information see the two-character ISO Standard Country Codes. Bank s SWIFT code. Unique address of the bank. Also known as the Bank Identification Code (BIC). Note This field is required when the IBAN is included in the request. The requestid value returned from a previous request for the bank transfer service. Unique identifier for the order submitted to Global Collect. Note If you do not include this field in a refund request, CyberSource will generate the value. Set to true to include the bank transfer refund service in your request. Set to true to include the bank transfer service in your request. Refund (See Bank Transfer (O) Refund (O) String (40) String (30) Refund (R) String (26) Refund (R for standalone refunds) String (60) Refund (R) String (5) Bank Transfer (R) String (5) billto_city City of the billing address. Bank Transfer (R) Refund (R) String (50) billto_company Name of the customer s company. Bank Transfer (O) String (60) billto_country billto_ Billing address country. Use the ISO Standard Country Codes. Customer s address, including the full domain name. For example: [email protected] Bank Transfer (R) Refund (R) Bank Transfer (R) Refund (R) billto_firstname Customer s first name. Bank Transfer (R) Refund (R) billto_lastname Customer s last name. Bank Transfer (R) 1. Required if billto_country value is US or CA 2. Required if any shipping information is included 3. Required if shipto_country value is US or CA Refund (R) String (2) String (255) String (60) String (60) Global Payment Service Developer Guide March

20 Chapter 2 Bank Transfers and Bank Transfer Refunds Using the Simple Order API Table 5 Request Fields for Bank Transfers and Bank Transfer Refunds for the Simple Order API (Continued) Request Field Description Used By and Required (R) or Optional (O) Data Type & Length billto_phonenumber Customer s telephone number. Bank Transfer (O) billto_postalcode Postal code for the billing address. The postal code must consist of 5 to 9 digits. If the value of billto_country is US, the 9-digit postal code must follow this format: [5 digits][dash][4 digits] Example: If the value of billto_country is CA, the 6-digit postal code must follow this format: [alpha][numeric][alpha] [numeric][alpha][numeric] Example: A1B 2C3 Refund (O) Bank Transfer (R) Refund (R) billto_state Billing address state. Bank Transfer (R) 1 Refund (R) 1 billto_street1 Billing address street address. Bank Transfer (R) Refund (R) billto_street2 Additional address information. Bank Transfer (O) fundtransfer_accountname Name used on the bank account. If you do not send this field, it is assumed the last name on the account is the billto_ lastname value. Some banks validate the name on the bank account, so consider sending this field if the bank account owner is not the customer. This scenario might happen, for example, if a husband places the order, but the wife s name is on the bank account. Contact CyberSource Customer Support for required country-specific bank account information. 1. Required if billto_country value is US or CA 2. Required if any shipping information is included 3. Required if shipto_country value is US or CA Refund (O) String (15) String (10) String (2) String (60) String (60) Refund (O) String (50) Global Payment Service Developer Guide March

21 Chapter 2 Bank Transfers and Bank Transfer Refunds Using the Simple Order API Table 5 Request Fields for Bank Transfers and Bank Transfer Refunds for the Simple Order API (Continued) Request Field Description Used By and Required (R) or Optional (O) Data Type & Length fundtransfer_accountnumber fundtransfer_bankcheckdigit fundtransfer_iban item_#_productcode Bank account number. Note From August 1, 2016, for euro countries and from October 31, 2016, for non-euro countries, the IBAN must be included in each request. If you provide a BBAN it will be converted to an IBAN, and this conversion process will continue only until August 1, Note Do not use the IBAN in this field. include the IBAN in the fundtransfer_ iban field. Code used to validate the customer's account number when you are not using the IBAN. Contact CyberSource Customer Support for required country-specific bank account information. International Bank Account Number (IBAN) for the bank account. Note Required for specific countries. Contact CyberSource Customer Support for required country-specific bank account information. Type of product, which is also used to determine the product category: electronic, handling, physical, service, or shipping. The default value is default. See "Product Codes," page 154, for a list of valid values. For bank transfers, if you set this field to a value other than default, stored_ value, or any of the values related to shipping and/or handling, the item_#_ quantity, item_#_productname, and item_#_productsku fields are required. item_#_productname Name of the product. For bank transfers, required if item_#_productcode is NOT default, stored_value, or one of the values related to shipping and/or handling. 1. Required if billto_country value is US or CA 2. Required if any shipping information is included 3. Required if shipto_country value is US or CA Refund (O) String (See Refund (O) String (2) Refund (See Bank Transfer (O) Refund (O) Bank Transfer (See Refund (O) String (30) String (30) String (30) Global Payment Service Developer Guide March

22 Chapter 2 Bank Transfers and Bank Transfer Refunds Using the Simple Order API Table 5 Request Fields for Bank Transfers and Bank Transfer Refunds for the Simple Order API (Continued) Request Field Description Used By and Required (R) or Optional (O) Data Type & Length item_#_productsku item_#_quantity item_#_taxamount item_#_unitprice Product identifier code. For bank transfers, required if item_#_ productcode is NOT default, stored_value, or one of the values related to shipping and/or handling. Quantity of the product being purchased. For bank transfers, required if item_#_ productcode is NOT default, stored_value, or one of the values related to shipping and/or handling. Tax amount associated with this item. The item_#_taxamount field is additive. For example, if you send one item with unitprice of and taxamount of 0.80, and you send another item with unitprice of and taxamount of 1.60, the total amount authorized will be for 32.40, not with 2.40 of tax included. The item_#_taxamount and the item_#_ unitprice must be in the same currency. If you include item_#_taxamount, and you also include taxservice in your request, taxservice does not calculate tax for the item. Instead, it returns the value in the item_#_taxamount field. Per-item price of the product. You must include either this field or purchasetotals_grandtotalamount in your request. This value cannot be negative. For more information, see Getting Started with CyberSource Advanced for the Simple Order API. You can include a decimal point (.) in this field, but you cannot include any other special characters. The amount will be truncated at the request level to the correct number of decimal places. 1. Required if billto_country value is US or CA 2. Required if any shipping information is included 3. Required if shipto_country value is US or CA Bank Transfer (See Refund (O) Bank Transfer (See Refund (O) Bank Transfer (O) Refund (O) Bank Transfer Refund (See String (30) Integer (10) String (15) String (15) Global Payment Service Developer Guide March

23 Chapter 2 Bank Transfers and Bank Transfer Refunds Using the Simple Order API Table 5 Request Fields for Bank Transfers and Bank Transfer Refunds for the Simple Order API (Continued) Request Field Description Used By and Required (R) or Optional (O) Data Type & Length linktorequest merchantid merchantreferencecode purchasetotals_currency purchasetotals_ grandtotalamount Value that links the current request to a previous authorization request for a debit card or prepaid card. This value is useful when multiple payment methods are used to complete an order. For more information, see Credit Card Services Using the Simple Order API. Your CyberSource merchant ID. Note When opening your account with CyberSource, be sure to inform CyberSource if you plan to use multiple CyberSource merchant IDs. For example, if you have separate business units within your company, each with a separate CyberSource merchant ID. You must have a separate processor merchant ID for each CyberSource merchant ID. For more information, contact CyberSource Customer Support. Merchant-generated order reference or tracking number. For more information, see Getting Started with CyberSource Advanced for the Simple Order API. Currency used for the order. Use the ISO Standard Currency Codes. Grand total for the order. You must include either this field or item_#_unitprice in your request. For more information, see Getting Started with CyberSource Advanced for the Simple Order API. Bank Transfer (O) String (26) Bank Transfer (R) Refund (R) Bank Transfer (R) Refund (R) Bank Transfer (R) Refund (R) Bank Transfer Refund See description String (30) String (50) String (5) String (15) shipto_city City of the shipping address. Bank Transfer (O) 2 String (50) shipto_country shipto_firstname Country of the shipping address. Use the two-character ISO Standard Country Codes. First name of the person receiving the product. shipto_lastname Last name of the person receiving the product. 1. Required if billto_country value is US or CA 2. Required if any shipping information is included 3. Required if shipto_country value is US or CA Bank Transfer (O) String (2) Bank Transfer (O) String (60) Bank Transfer (O) String (60) Global Payment Service Developer Guide March

24 Chapter 2 Bank Transfers and Bank Transfer Refunds Using the Simple Order API Table 5 Request Fields for Bank Transfers and Bank Transfer Refunds for the Simple Order API (Continued) Request Field Description Used By and Required (R) or Optional (O) Data Type & Length shipto_phonenumber Phone number for the shipping address. Bank Transfer (O) String (15) shipto_postalcode shipto_state Postal code for the shipping address. The postal code must consist of 5 to 9 digits. If the value of shipto_country is US, the 9-digit postal code must follow these rules: [5 digits][dash][4 digits] Example: If the value of shipto_country is CA, the 6-digit postal code must follow these rules: [alpha][numeric][alpha] [numeric][alpha][numeric] Example: A1B 2C4 If the postal code for the shipping address is not included in the request message, CyberSource uses the postal code from the billing address. If the postal code for the billing address is not included in the request message, the postal code for the shipping address is required. State or province of the shipping address. Use the State, Province, and Territory Codes for the United States and Canada. Bank Transfer (O) 3 String (10) Bank Transfer (O) 3 String (2) shipto_street1 First line of the shipping address. Bank Transfer (O) 2 String (60) shipto_street2 Second line of the shipping address. Bank Transfer (O) String (60) 1. Required if billto_country value is US or CA 2. Required if any shipping information is included 3. Required if shipto_country value is US or CA Global Payment Service Developer Guide March

25 Chapter 2 Bank Transfers and Bank Transfer Refunds Using the Simple Order API Reply Fields The following table lists the fields returned in a reply from banktransferservice or banktransferrefundservice service request. Table 6 Bank Transfer and Bank Transfer Refund Reply Fields for the Simple Order API Reply Field Description Returned By Data Type & Length banktransferrefundreply_ amount Total amount for the bank transfer refund. Refund String (15) banktransferrefundreply_ iban banktransferrefundreply_ processorresponse banktransferrefundreply_ reasoncode banktransferrefundreply_ reconciliationid banktransferrefundreply_ requestdatetime banktransferreply_ accountholder banktransferreply_ accountnumber International Bank Account Number (IBAN) for the bank account. Refund Alphanumeric (50) Response code from the processor. Refund String (10) A numeric value corresponding to the result of the bank transfer refund request. See "Reason Codes," page 155, for a list of possible values. Unique value generated by CyberSource. For more information, see Getting Started with CyberSource Advanced for the Simple Order API. Time the bank transfer refund was requested. Format: YYYY-MM-DDThh:mm:ssZ. Example: T22:47:57Z, which is August 11, 2007, at 10:47:57 P.M. The T separates the date and the time. The Z indicates UTC. Refund Integer (5) Refund String (60) Refund String (20) Name of the account holder. Bank Transfer String (50) Bank account number. Use the contents of this field along with the contents of the banktransferreply_bankspecialid field to display the country s traditional representation of the full bank account number on the bank transfer confirmation page. Contact CyberSource Customer Support for required country-specific bank account information. Bank Transfer String (30) banktransferreply_amount Total amount for the bank transfer. Bank Transfer String (15) banktransferreply_bankcity City in which the bank is located. Bank Transfer String (50) banktransferreply_ bankcountry Country in which the bank is located. Bank Transfer String (50) Global Payment Service Developer Guide March

26 Chapter 2 Bank Transfers and Bank Transfer Refunds Using the Simple Order API Table 6 Bank Transfer and Bank Transfer Refund Reply Fields for the Simple Order API (Continued) Reply Field Description Returned By Data Type & Length banktransferreply_ bankname banktransferreply_ bankspecialid banktransferreply_ bankswiftcode banktransferreply_iban banktransferreply_ paymentreference banktransferreply_ processorresponse banktransferreply_ reasoncode banktransferreply_ reconciliationid Name of the bank. Bank Transfer String (50) Special ID used for the bank. For example, the sort code for U.K. banks. This field is only for the Global Collect processor. Use the contents of this field along with the contents of the banktransferreply_accountnumber field to display the country s traditional representation of the full bank account number on the bank transfer confirmation page. Contact CyberSource Customer Support for required country-specific bank account information. Bank s SWIFT code. Unique address of the bank. Also known as the Bank Identification Code (BIC). If this field is in the reply, display the value to the customer along with the other bank information. International Bank Account Number (IBAN) for the bank account. If this field is in the reply, display the value to the customer along with the other bank information. Note Required for specific countries. Contact CyberSource Customer Support for required country-specific bank account information. Payment reference number that you must display to the customer. For more information, see Getting Started with CyberSource Advanced for the Simple Order API. In Italy, this is called the Numero di riferimento. Bank Transfer String (50) Bank Transfer String (50) Bank Transfer String (30) Bank Transfer String (16) Response code from the processor. Bank Transfer String (10) A numeric value corresponding to the result of the bank transfer request. See "Reason Codes," page 155, for a list of possible values. Unique value generated by CyberSource. For more information, see Getting Started with CyberSource Advanced for the Simple Order API. Bank Transfer Integer (5) Bank Transfer String (60) Global Payment Service Developer Guide March

27 Chapter 2 Bank Transfers and Bank Transfer Refunds Using the Simple Order API Table 6 Bank Transfer and Bank Transfer Refund Reply Fields for the Simple Order API (Continued) Reply Field Description Returned By Data Type & Length banktransferreply_ requestdatetime decision Time the bank transfer was requested. Format: YYYY-MM-DDThh:mm:ssZ. Example: T22:47:57Z, which is August 11, 2005, at 10:47:57 P.M. The T separates the date and the time. The Z indicates UTC. Summarizes the result of the overall request. Possible values: ACCEPT ERROR REJECT Bank Transfer String (20) Bank Transfer and Refund String (6) invalidfield_0...n merchantreferencecode missingfield_0...n purchasetotals_currency reasoncode Fields in the request that contained invalid data. These reply fields are included as an aid to software developers only. No attempt should be made to use these fields for end user interaction. For more information, see Getting Started with CyberSource Advanced for the Simple Order API. Order reference or tracking number that you provided in the request. If you included multibyte characters in this field in the request, the returned value might contain corrupted characters. Required fields that were missing from the request. These reply fields are included as an aid to software developers only. No attempt should be made to use these fields for end user interaction. For more information, see Getting Started with CyberSource Advanced for the Simple Order API. Currency used for the order. Uses the ISO Standard Currency Codes. Numeric value corresponding to the result of the overall request. See "Reason Codes," page 155, for a list of possible values. Bank Transfer and Refund Bank Transfer and Refund Bank Transfer and Refund Bank Transfer and Refund Bank Transfer and Refund requestid Identifier for the request. Bank Transfer and Refund String (100) String (50) String (100) String (5) Integer (5) String (26) Global Payment Service Developer Guide March

28 Chapter 2 Bank Transfers and Bank Transfer Refunds Using the Simple Order API Request and Reply Examples Bank Transfer Request Example 1 Bank Transfer Request <requestmessage xmlns="urn:schemas-cybersource-com:transaction-data-1.23"> <merchantid>infodev</merchantid> <merchantreferencecode>482046c3a7e94f5</merchantreferencecode> <billto> <firstname>john</firstname> <lastname>smith</lastname> <street1>boschdijk 987</street1> <city>eindhoven</city> <postalcode>5600 PB</postalCode> <country>nl</country> < >[email protected]</ > </billto> <bankinfo> <bankcountry>nl</bankcountry> <bankcity>amsterdam</bankcountry> <bankname>abn Amro Bank N.V</bankName> <swiftcode>abna NL 2A</swiftCode> </bankinfo> <fundtransfer> <accountnumber> </accountnumber> </fundtransfer> <item id="0"> <unitprice>49.95</unitprice> <quantity>1</quantity> </item> <purchasetotals> <currency>gbp</currency> </purchasetotals> <banktransferservice run="true"/> </requestmessage> Global Payment Service Developer Guide March

29 Chapter 2 Bank Transfers and Bank Transfer Refunds Using the Simple Order API Bank Transfer Reply Example 2 Bank Transfer Reply <c:replymessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.23"> <c:merchantreferencecode>482046c3a7e94f5</c:merchantreferencecode> <c:requestid> </c:requestid> <c:decision>accept</c:decision> <c:reasoncode>100</c:reasoncode> <c:purchasetotals> <c:currency>eur</c:currency> </c:purchasetotals> <c:banktransferreply> <c:reasoncode>100</c:reasoncode> <c:accountholder>global Collect BV</c:accountHolder> <c:accountnumber> </c:accountnumber> <c:amount>49.95</c:amount> <c:bankname>abn Amro Bank N.V</c:bankName> <c:bankcity>amsterdam</c:bankcity> <c:bankcountry>nl</c:bankcountry> <c:paymentreference> </c:paymentreference> <c:bankswiftcode>abna NL 2A</c:bankSwiftCode> <c:bankspecialid> </c:bankspecialid> <c:requestdatetime> t23:44:27z</c:requestdatetime> <c:reconciliationid> </c:reconciliationid> </c:banktransferreply> </c:replymessage> Global Payment Service Developer Guide March

30 Chapter 2 Bank Transfers and Bank Transfer Refunds Using the Simple Order API Example 3 Standalone Bank Transfer Refund Request Standalone Bank Transfer Refund Request <requestmessage xmlns="urn:schemas-cybersource-com:transaction-data-1.103"> <merchantid>demo123</merchantid> <merchantreferencecode>demoref</merchantreferencecode> <billto> <firstname>orlando</firstname> <lastname>bloom</lastname> <street1>33, rue Dauphine</street1> <city>bergheim</city> <postalcode>75006</postalcode> <country>de</country> <phonenumber> </phoneNumber> < >[email protected]</ > </billto> <purchasetotals> <currency>eur</currency> <grandtotalamount>112</grandtotalamount> </purchasetotals> <fundtransfer> <accountnumber> </accountnumber> <accountname>bradford NICKLES</accountName> </fundtransfer> <bankinfo> <bankcode> </bankcode> <name>sloveniabank_testing</name> <country>de</country> <swiftcode>bsljsi2x</swiftcode> </bankinfo> <banktransferrefundservice run="true"> <reconciliationid> </reconciliationid> </banktransferrefundservice> </requestmessage> Global Payment Service Developer Guide March

31 Chapter 2 Bank Transfers and Bank Transfer Refunds Using the Simple Order API Example 4 Standalone Bank Transfer Refund Reply Standalone Bank Transfer Refund Reply <c:replymessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.103"> <c:merchantreferencecode>demoref</c:merchantreferencecode> <c:requestid> </c:requestid> <c:decision>accept</c:decision> <c:reasoncode>100</c:reasoncode> <c:purchasetotals> <c:currency>eur</c:currency> </c:purchasetotals> <c:banktransferrefundreply> <c:reasoncode>100</c:reasoncode> <c:amount>112.00</c:amount> <c:requestdatetime> t23:39:14z</c:requestdatetime> <c:reconciliationid> </c:reconciliationid> <c:iban>de </c:iban> </c:banktransferrefundreply> </c:replymessage> Example 5 Follow-On Bank Transfer Refund Request Follow-On Bank Transfer Refund Request <requestmessage xmlns="urn:schemas-cybersource-com:transaction-data-1.103"> <merchantid>demo123</merchantid> <merchantreferencecode>demoref</merchantreferencecode> <billto> <firstname>orlando</firstname> <lastname>bloom</lastname> <street1>33, rue Dauphine</street1> <city>bergheim</city> <postalcode>75006</postalcode> <country>de</country> <phonenumber> </phoneNumber> < >[email protected]</ > </billto> <purchasetotals> <currency>eur</currency> <grandtotalamount>74</grandtotalamount> </purchasetotals> <fundtransfer> <accountnumber> </accountnumber> <accountname>bradford NICKLES</accountName> </fundtransfer> Global Payment Service Developer Guide March

32 Chapter 2 Bank Transfers and Bank Transfer Refunds Using the Simple Order API <bankinfo> <bankcode> </bankcode> <name>sloveniabank_testing</name> <country>de</country> <swiftcode>bsljsi2x</swiftcode> </bankinfo> <banktransferservice run="true"/> </requestmessage> Example 6 Follow-On Bank Transfer Refund Reply Follow-On Bank Transfer Refund Reply <c:replymessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.103"> <c:merchantreferencecode>demoref</c:merchantreferencecode> <c:requestid> </c:requestid> <c:decision>accept</c:decision> <c:reasoncode>100</c:reasoncode> <c:purchasetotals> <c:currency>eur</c:currency> </c:purchasetotals> <c:banktransferreply> <c:reasoncode>100</c:reasoncode> <c:accountholder>global Collect B.V.</c:accountHolder> <c:accountnumber> </c:accountnumber> <c:amount>74.00</c:amount> <c:bankname>postbank AG</c:bankName> <c:bankcity>leipzig</c:bankcity> <c:bankcountry>germany</c:bankcountry> <c:paymentreference> </c:paymentreference> <c:bankswiftcode>pbnkdeff</c:bankswiftcode> <c:bankspecialid>blz </c:bankSpecialID> <c:requestdatetime> t23:40:19z</c:requestdatetime> <c:reconciliationid> </c:reconciliationid> <c:iban>de </c:iban> </c:banktransferreply> </c:replymessage> Global Payment Service Developer Guide March

33 Bank Transfers and Bank Transfer Refunds Using the SCMP API CHAPTER 3 Requesting Bank Transfers Use the ics_bank_transfer service to request a bank transfer. See Table 7, page 36, for a list of the fields to use when requesting the service. When requesting a bank transfer, you may not request any of the other ICS services except ics_tax. For more information about the service, see Tax Calculation Service Using the SCMP API. In the bank transfer reply, you will receive fields containing information about the bank and bank account that the customer should transfer funds to. You need to display this information to customers so that they can easily transcribe it or print it and give it to their banks. The information includes the bank s name, bank s country, the account holder s name, and so on. The primary field containing the bank account information is bank_transfer_ account_number. This field contains the necessary bank account number information you need to display, including a bank code or sort code, branch code, or check digit, if any of those are used for the particular country. You can display the contents of the field as you receive it in the reply from CyberSource. You might also receive bank_transfer_iban with the International Bank Account Number (IBAN). The IBAN is a international standard for bank account numbers that the EU is adopting. In the future, the EU is planning to switch to using only the IBAN format and not the original format presented in bank_transfer_account_number. If the IBAN is present in the reply, display it to the customer along with the other bank information, and identify it as the IBAN. Depending on the country, you might also receive the bank s SWIFT code, which is another bank identifier. If the bank_transfer_swiftcode field is present, display it to the customer along with the other bank information, and identify it as the SWIFT code. Global Payment Service Developer Guide March

34 Chapter 3 Bank Transfers and Bank Transfer Refunds Using the SCMP API Requesting Bank Transfer Refunds Important From August 1, 2016, for euro countries and from October 31, 2016, for noneuro countries, the IBAN must be included in each request. If you provide a BBAN it will be converted to an IBAN, and this conversion process will continue only until August 1, Important A follow-on refund must occur within 60 days of the request for the bank transfer. After the time limit expires, only a stand-alone refund can be requested. To refund a bank transfer, wait 1 to 3 days after the bank transfer request is processed by CyberSource. When you attempt to request a followon refund before the initial bank transfer is processed into your merchant bank account, the error ORDER WITHOUT REFUNDABLE PAYMENTS is displayed. This error could also mean that your account is not configured for standalone refunds with Global Collect. To configure your account, please contact CyberSource Customer Support. There are two types of bank transfer refunds: follow-on refunds and stand-alone refunds. A follow-on refund uses information from a previous bank transfer. A stand-alone refund does not depend on a previous transaction. To request a bank transfer refund: Use the ics_bank_transfer_refund service to request a bank transfer refund. Do not request any other ICS services except Tax Calculation, which is optional. For more information about this service, see Tax Calculation Service Using the SCMP API. Send the fields required for a bank transfer refund request as described in Table 7, page 36. For a follow-on refund, the fields and values must match the fields and values that you sent in the bank transfer request. For a follow-on refund, include one of these fields from the original request with the request ID: bank_transfer_request_id bank_transfer_real_time_request_id For a stand-alone refund, the bank_transfer_request_id field is optional. The easiest way to implement bank transfer refunds is to always send the request ID from the original bank transfer with every bank transfer refund request. Global Payment Service Developer Guide March

35 Chapter 3 Bank Transfers and Bank Transfer Refunds Using the SCMP API CyberSource recommends that when you request a refund, you use the same value for merchant_ref_number that you used for the bank transfer. This makes it easier for you to link the refund to the original bank transfer in your own system as well as in CyberSource reports and Transaction Search Screens. CyberSource validates the bank account number before processing the bank transfer refund. If the account number does not pass the validation check, CyberSource rejects the request with a rflag=dinvalidaccount. CyberSource recommends that you then confirm the customer entered the number correctly, and if it was incorrect, request the refund again with the correct number. You may perform multiple partial refunds against a bank transfer. The sum of the refunds may not exceed the amount of the payment. You will not receive an error in the reply for any of the following conditions: The bank_transfer_request_id is invalid. The customer s payment has not yet been received. Instead, CyberSource will not process the refund and the transaction will appear in the daily Transaction Exception Detail Report. You should monitor this report daily to determine if any of your transactions have problems. For information about the report and how to use it, see the Global Payment Service Planning Guide. For details about downloading the report and its format, see the Reporting Developer Guide. Researching a Missing Payment If a customer calls to say that they have made the bank transfer payment but have not received the goods, and CyberSource s report or your bank account statement does not show that you have received the payment, you can make a payment inquiry in the Business Center and have CyberSource research the lost payment. Note You must wait at least five days after the funds are debited from the customer s account before initiating an inquiry because it can take that long before the funds appear in your account and in CyberSource s reports. CyberSource will not allow you to perform an inquiry within five days of submitting the initial bank transfer request. For instructions on how to research a lost payment in the Business Center, see Appendix C, "Researching a Missing Bank Transfer Payment," on page 158. Global Payment Service Developer Guide March

36 Chapter 3 Bank Transfers and Bank Transfer Refunds Using the SCMP API API Fields The following table lists the fields to use in requests for bank transfers and bank transfer refunds. See the information about data types in Getting Started with CyberSource Advanced for the SCMP API. Request Fields The following table lists the fields to use in a request for ics_bank_transfer or ics_bank_ transfer_refund. Table 7 Request-Level Fields for Bank Transfers and Bank Transfer Refunds for the SCMP API Request-Level Field bank_account_name bank_account_ number Description Name used on the bank account. If you do not send this field, it is assumed the last name on the account is customer_lastname. Some banks validate the name on the bank account, so consider sending this field if the bank account owner is not the customer.this scenario might happen, for example, if a husband places the order, but the wife s name is on the bank account. Contact CyberSource Customer Support for required country-specific bank account information. Bank account number. Contact CyberSource Customer Support for required country-specific bank account information. Note From August 1, 2016, for euro countries and from October 31, 2016, for non-euro countries, the IBAN must be included in each request. If you provide a BBAN it will be converted to an IBAN, and this conversion process will continue only until August 1, Note Do not use the IBAN in this field. Use only the traditional account number information. For the IBAN, use the bank_iban field. Used by and Required (R) or Optional (O) Data Type & Length Refund (O) String (50) Refund (O) String (See bank_address Bank s address. Refund (O) String (255) 1. Required if bill_country value is US or CA 2. Required if any shipping information is included 3. Required if ship_to_country value is US or CA Global Payment Service Developer Guide March

37 Chapter 3 Bank Transfers and Bank Transfer Refunds Using the SCMP API Table 7 Request-Level Fields for Bank Transfers and Bank Transfer Refunds for the SCMP API (Continued) Request-Level Field bank_check_digit bank_city bank_code bank_country bank_iban bank_name bank_swiftcode bank_transfer_ request_id Description Code used to validate the customer's account number when you are not using the IBAN. Contact CyberSource Customer Support for required country-specific bank account information. City where the bank is located. Some banks validate the bank account information, so consider sending this field if the bank is not located in bill_ city. Bank's code. Used for some countries when you are not using the IBAN. Contact CyberSource Customer Support for required country-specific bank account information. Note This is a required field if the bank_country field is GB, AT, FR, or DE. For more information see the two-character ISO Standard Country Codes. Country where the bank is located. Use the twocharacter ISO Standard Country Codes. Note If bank_country is not set, CyberSource uses bill_country to determine the country in which the bank transfer is taking place. International Bank Account Number (IBAN) for the bank account. Note Required for specific countries. Contact CyberSource Customer Support for required country-specific bank account information. Bank's name. 1. Required if bill_country value is US or CA 2. Required if any shipping information is included 3. Required if ship_to_country value is US or CA Note This is a required field if the bank_country field is AU, FI, FR, IT, NO, ES, SE, or CH. For more information see the two-character ISO Standard Country Codes. Bank s SWIFT code. Unique address of the bank. Also known as the Bank Identification Code (BIC). Note This field is required when the IBAN field is included in the request. The request_id value returned from a previous request for ics_bank_transfer. Used by and Required (R) or Optional (O) Refund (O) String (2) Refund (O) String (40) Refund (See Bank Transfer (See Refund (R) Refund (See Refund (See Bank Transfer (See Refund (O) Data Type & Length String (See String (2) String (30) String (40) String (30) Refund (R) String (26) Global Payment Service Developer Guide March

38 Chapter 3 Bank Transfers and Bank Transfer Refunds Using the SCMP API Table 7 Request-Level Fields for Bank Transfers and Bank Transfer Refunds for the SCMP API (Continued) Request-Level Field bank_transfer_trans_ ref_no Unique identifier for the order submitted to Global Collect. Note If you do not include this field in a refund request, CyberSource will generate the value. Refund (R for standalone refunds) bill_address1 Billing street address. Bank Transfer (R) Refund (R) bill_address2 Additional billing address information. Bank Transfer (O) Refund (O) bill_city Billing address city. Bank Transfer (R) Refund (R) bill_country Billing address country. Bank Transfer (R) Refund (R) String (60) String (60) String (60) String (50) String (2) bill_state Billing address state. Bank Transfer (R) 1 Refund (R) 1 String (2) bill_zip branch_code Zip code for the shipping address. The zip code must consist of 5 to 9 digits. If the value of bill_country is US, the 9-digit zip code must follow this format: [5 digits][dash][4 digits] Example: If the value of bill_country is CA, the 6-digit zip code must follow this format: [alpha][numeric][alpha] [numeric][alpha][numeric] Example: A1B 2C3 Code that identifies the branch of the customer's bank when you are not using the IBAN. Contact CyberSource Customer Support for required country-specific bank account information. Bank Transfer (R if bill_country is US or CA) Refund (R if bill_ country is US or CA) String (10) Refund (O) String (15) company_name Name of the customer s company. Bank Transfer (O) String (60) currency customer_ Description Currency used for the order. Use the ISO Standard Currency Codes. Customer s address. For example: [email protected] 1. Required if bill_country value is US or CA 2. Required if any shipping information is included 3. Required if ship_to_country value is US or CA Used by and Required (R) or Optional (O) Bank Transfer (R) Refund (R) Bank Transfer (R) Refund (R) Data Type & Length String (5) String (255) Global Payment Service Developer Guide March

39 Chapter 3 Bank Transfers and Bank Transfer Refunds Using the SCMP API Table 7 Request-Level Fields for Bank Transfers and Bank Transfer Refunds for the SCMP API (Continued) Request-Level Field customer_firstname Customer s first name. Bank Transfer (R) Refund (R) customer_lastname Customer s last name. Bank Transfer (R) Refund (R) customer_phone Customer s telephone number. Bank Transfer (O) grand_total_amount Grand total for the order. You must include either this field or offer0 and the offer-level field amount. See the information about offers and grand totals in Getting Started with CyberSource Advanced for the SCMP API. Refund (O) Bank Transfer Refund See description ics_applications ICS services to process for the request. Bank Transfer (R) link_to_request merchant_id merchant_ref_ number offer0...n Description Value that links the current request to a previous authorization request for a debit card or prepaid card. This value is useful when using multiple payment methods to complete an order. For details, see the information about partial authorizations in Credit Card Services Using the SCMP API. Your CyberSource merchant ID. 1. Required if bill_country value is US or CA 2. Required if any shipping information is included 3. Required if ship_to_country value is US or CA Note When opening your account with CyberSource, make sure to inform CyberSource if you plan to use multiple CyberSource merchant IDs. For example, if you have separate business units within your company, each with a separate CyberSource merchant ID. You must have a separate processor merchant ID for each CyberSource merchant ID. For more information, contact CyberSource Customer Support. Merchant-generated order reference or tracking number. See the information about tracking orders in Getting Started with CyberSource Advanced for the SCMP API. Offers for the request. An offer is a line item for the order. Used by and Required (R) or Optional (O) Refund (R) String (60) String (60) String (15) Decimal (15) String (255) Bank Transfer (O) String (26) Bank Transfer (R) Refund (R) Bank Transfer (R) Refund (R) Bank Transfer (O) Refund (O) Data Type & Length String (30) String (50) String (50) Global Payment Service Developer Guide March

40 Chapter 3 Bank Transfers and Bank Transfer Refunds Using the SCMP API Table 7 Request-Level Fields for Bank Transfers and Bank Transfer Refunds for the SCMP API (Continued) Request-Level Field ship_to_address1 ship_to_address2 First line of the address to which to ship the product. Second line of the address to which to ship the product. Bank Transfer (O) 2 String (60) Bank Transfer (O) String (60) ship_to_city City to which to ship the product. Bank Transfer (O) 2 String (50) ship_to_country Country to which to ship the product. Use the twocharacter ISO Standard Country Codes. Bank Transfer (O) String (2) ship_to_firstname First name of person receiving the product. Bank Transfer (O) String (60) ship_to_lastname Last name of person receiving the product. Bank Transfer (O) String (60) ship_to_phone Phone number for the shipping address. Bank Transfer (O) String (15) ship_to_state ship_to_zip timeout Description State or province to which to ship the product. Use the State, Province, and Territory Codes for the United States and Canada. Zip code for the shipping address. 1. Required if bill_country value is US or CA 2. Required if any shipping information is included 3. Required if ship_to_country value is US or CA If the value of ship_to_country is US, the 9-digit zip code must follow this format: [5 digits][dash][4 digits] Example: If the value of ship_to_country is CA, the 6-digit zip code must follow this format: [alpha][numeric][alpha] [numeric][alpha][numeric] Example: A1B 2C3 If the postal code for the shipping address is not included in the request message, CyberSource will use the postal code for the billing address. If the postal code for the billing address is not included in the request message, the postal code for the shipping address is required. Number of seconds until the transaction times out. The default is 110 seconds. Used by and Required (R) or Optional (O) Bank Transfer (O) 3 String (2) Bank Transfer (O) 3 String (10) Bank Transfer (O) Refund (O) Data Type & Length Positive integer (3) Global Payment Service Developer Guide March

41 Chapter 3 Bank Transfers and Bank Transfer Refunds Using the SCMP API Offer-Level Fields The following table lists the offer-level fields to use in a request for ics_bank_transfer or ics_bank_transfer_refund. Table 8 Offer-Level Fields for Bank Transfers and Bank Transfer Refunds for the SCMP API Offer-Level Field Description Used by and Required (R) or Optional (O) Data Type & Length amount Per-item price of the product. You must include either offer0 and this field, or the request-level field grand_total_amount in your request. This value cannot be negative. See the information about offers and grand totals in Getting Started with CyberSource Advanced for the SCMP API. Bank Transfer (See Refund (See Decimal (15) You can include a decimal point (.) in this field, but you cannot include any other special characters. The amount will be truncated at the request level to the correct number of decimal places. merchant_product_ sku Product identifier code. It is required for bank transfers if product_code is not default, stored_value, or one of the values related to shipping and/or handling. Bank Transfer (See Refund (O) String (30) product_code Type of product that the offer contains, which is also used to determine the category that the product falls under: electronic, handling, physical, service, or shipping. The default value is default. See "Product Codes," page 154, for a list of valid values. Bank Transfer (O) Refund (O) String (30) For bank transfers, if you set this to a value other than default, stored_value, or any of the values related to shipping and/or handling, the quantity, product_name, and merchant_ product_sku fields are required. product_name Name of the product. For bank transfers, required if product_code is NOT default, stored_ value, or one of the values related to shipping and/or handling. Bank Transfer (See Refund (O) String (30) quantity Quantity of the product being purchased. The default value is 1. For bank transfers, required if product_code is NOT default, stored_ value or one of the values related to shipping and/or handling. Bank Transfer (See Refund (O) Nonnegative integer (10) Global Payment Service Developer Guide March

42 Chapter 3 Bank Transfers and Bank Transfer Refunds Using the SCMP API Table 8 Offer-Level Fields for Bank Transfers and Bank Transfer Refunds for the SCMP API (Continued) Offer-Level Field Description Used by and Required (R) or Optional (O) Data Type & Length tax_amount Tax amount associated with this item. The tax_ amount field is additive. For example, if you send these offer lines: Bank Transfer (O) Refund (O) Decimal (15) offer0=amount:10.00^ quantity:1^tax_amount:0.80 offer1=amount:20.00^ quantity:1^tax_amount:1.60 the total amount authorized will be for 32.40, not with 2.40 of tax included. The tax_amount and the amount must be in the same currency. If you include tax_amount, and you request the ics_tax service, ics_tax will not calculate tax for the offer. Instead, it will return the value in the tax_ amount field. Reply Fields The following table lists the fields returned in a reply from ics_bank_transfer or ics_ bank_transfer_refund. Table 9 Reply Fields for Bank Transfers and Bank Transfer Refunds for the SCMP API Reply Field Description Returned By Data Type & Length bank_transfer_account_ holder Name of the account holder. Bank Transfer String (50) bank_transfer_account_ number Bank account number. Use the contents of this field along with the contents of the bank_transfer_ special_id field to display on the bank transfer confirmation page the country s traditional representation of the full bank account number. Contact CyberSource Customer Support for required country-specific bank account information. Bank Transfer String (30) bank_transfer_amount Total amount for the bank transfer. Bank Transfer Decimal (15) bank_transfer_bank_city City in which the bank is located. Bank Transfer String (50) bank_transfer_bank_ country Country in which the bank is located. Bank Transfer String (50) Global Payment Service Developer Guide March

43 Chapter 3 Bank Transfers and Bank Transfer Refunds Using the SCMP API Table 9 Reply Fields for Bank Transfers and Bank Transfer Refunds for the SCMP API (Continued) Reply Field Description Returned By bank_transfer_bank_ name bank_transfer_iban bank_transfer_ payment_reference bank_transfer_rcode bank_transfer_refund_ amount bank_transfer_refund iban bank_transfer_refund_ rcode bank_transfer_refund_ response_code bank_transfer_refund_ rflag bank_transfer_refund_ rmsg bank_transfer_refund_ time bank_transfer_refund_ trans_ref_no bank_transfer_request_ time bank_transfer_ response_code bank_transfer_rflag bank_transfer_rmsg Bank s name. Bank Transfer String (50) International Bank Account Number (IBAN) for the bank account. If this field is in the reply, display the value to the customer along with the other bank information. Note Contact CyberSource Customer Support for required country-specific bank account information. Payment reference number that you must display to the customer. For more information, see Getting Started with CyberSource Advanced for the SCMP API. In Italy, this is called the Numero di riferimento. One-digit code that indicates whether the ics_ bank_transfer request was successful. Bank Transfer String (30) Bank Transfer String (16) Bank Transfer Integer (1) Amount of the bank transfer refund. Refund Decimal (15) International Bank Account Number (IBAN) for the bank account. One-digit code that indicates whether the ics_ bank_transfer_refund request was successful. Refund Alphanumeric (50) Refund Integer (1) Response code from the processor. Refund String (10) One-word description of the result of the ics_bank_ transfer_refund request. Message that explains the reply flag bank_ transfer_refund_rflag. Time of bank transfer refund request in UTC format. For more information, see Getting Started with CyberSource Advanced for the SCMP API. Unique value generated by CyberSource. See the information about tracking orders in Getting Started with CyberSource Advanced for the SCMP API. Time of the bank transfer request in UTC format. For more information, see Getting Started with CyberSource Advanced for the SCMP API. Refund String (50) Refund String (255) Refund Date and time (20) Refund String (60) Bank Transfer Date and time (20) Response code from the processor. Bank Transfer String (10) One-word description of the result of the ics_bank_ transfer request. Message that explains the reply flag bank_ transfer_rflag. Data Type & Length Bank Transfer String (50) Bank Transfer String (255) Global Payment Service Developer Guide March

44 Chapter 3 Bank Transfers and Bank Transfer Refunds Using the SCMP API Table 9 Reply Fields for Bank Transfers and Bank Transfer Refunds for the SCMP API (Continued) Reply Field Description Returned By bank_transfer_special_ id bank_transfer_swiftcode bank_transfer_trans_ ref_no client_lib_version currency ics_rcode Contains any special ID used for the bank. For example, the sort code for U.K. banks. This field is only for the Global Collect processor. Use the contents of this field along with the contents of the bank_transfer_account_number field to display on the bank transfer confirmation page the country s traditional representation of the full bank account number. Contact CyberSource Customer Support for required country-specific bank account information. Bank s SWIFT code. Unique address of the bank. If this field is in the reply, display the value to the customer along with the other bank information. Unique value generated by CyberSource. For more information, see Getting Started with CyberSource Advanced for the SCMP API. Information about the client library used to request the transaction. Currency used for the order. Uses the ISO Standard Currency Codes. One-digit code that indicates whether the entire request was successful. The field will contain one of the following values: -1: An error occurred 0: The request was declined 1: The request was successful Bank Transfer String (50) Bank Transfer String (50) Bank Transfer String (60) Bank Transfer and Refund Bank Transfer and Refund Bank Transfer and Refund Data Type & Length String (50) String (5) Integer (1) ics_rflag One-word description of the result of the entire request. Bank Transfer and Refund ics_rmsg Message that explains the reply flag ics_rflag. Bank Transfer and Refund merchant_ref_number Order reference or tracking number that you provided in the request. If you included multi-byte characters in this field in the request, the returned value might contain corrupted characters. Bank Transfer and Refund request_id Identifier for the request generated by CyberSource. Bank Transfer and Refund String (50) String (255) String (50) String (26) Global Payment Service Developer Guide March

45 Chapter 3 Bank Transfers and Bank Transfer Refunds Using the SCMP API Reply Flags The following table lists the reply flags for ics_bank_transfer and ics_bank_transfer_ refund. Table 10 Reply Flags for Bank Transfer and Bank Transfer Refunds for the SCMP API Reply Flag Description Returned by DINVALIDACCOUNT The bank account number did not pass the validation check. Verify with the customer that the account number is correct; if it was incorrect, request the service again with the corrected information. Applies to bank transfer refunds with banks in France, Germany, and the United Kingdom. Bank Transfer Refund DINVALIDDATA Data provided is not consistent with the request. Bank Transfer and Refund DMISSINGFIELD The request is missing a required field. Bank Transfer and Refund ESYSTEM System error. You must design your transaction management system to correctly handle CyberSource system errors. Depending on the payment processor handling the transaction, the error may indicate a valid CyberSource system error or a processor rejection due to invalid data. In either case, CyberSource recommends that you do not design your system to endlessly retry sending a transaction. For important information on handling system errors and retries, see the documentation for your CyberSource client. Bank Transfer and Refund ETIMEOUT The request timed out. Bank Transfer and Refund SOK The transaction was successful. Bank Transfer and Refund Global Payment Service Developer Guide March

46 Chapter 3 Bank Transfers and Bank Transfer Refunds Using the SCMP API Request and Reply Examples Bank Transfer Request Example 7 Bank Transfer Request bill_address1=boschdijk 987 bill_city=eindhoven bill_country=nl bill_zip=5600 PB currency=eur customer_ [email protected] customer_firstname=john customer_lastname=smith bank_country=nl bank_city=amsterdam bank_name=abn Amro bank_swiftcode=abna NL 2A bank_account_number= ics_applications=ics_bank_transfer merchant_id=infodev merchant_ref_number=482046c3a7e94f5bd1fe3c66c offer0=amount:49.95^quantity:1 Global Payment Service Developer Guide March

47 Chapter 3 Bank Transfers and Bank Transfer Refunds Using the SCMP API Bank Transfer Reply Example 8 Bank Transfer Reply merchant_ref_number=482046c3a7e94f5bd1fe3c66c currency=eur ics_rcode=1 ics_rflag=sok ics_rmsg=request was processed successfully. request_id= bank_transfer_trans_ref_no= bank_transfer_amount=49.95 bank_transfer_bank_country=nl bank_transfer_account_holder=global Collect BV bank_transfer_bank_name=abna NL 2A bank_transfer_bank_city=amsterdam bank_transfer_swiftcode=abna NL 2A bank_transfer_time= t170910z bank_transfer_payment_reference= bank_transfer_response_code=800 bank_transfer_special_id= bank_transfer_account_number= bank_transfer_rcode=1 bank_transfer_rflag=sok bank_transfer_rmsg=request was processed successfully. client_lib_version=perl3.2/mswin324.0/nt4.0/win32/c/3.4.5 Global Payment Service Developer Guide March

48 Chapter 3 Bank Transfers and Bank Transfer Refunds Using the SCMP API Standalone Bank Transfer Refund Request Example 9 Standalone Bank Transfer Refund Request ics_applications=ics_bank_transfer_refund bank_account_name=nette bank_account_number= bank_check_digit=12 bank_city=paris bank_code= bank_country=france bank_name=bnp Paribas bill_address1=1ere Avenue bill_address2=14eme Rue BP 148 bill_city=carros Cedex bill_country=fr bill_zip=06513 branch_code= abcde currency=eur customer_ [email protected] customer_firstname=antoi customer_lastname=nette customer_phone= merchant_id=mercid123 merchant_ref_number=merref123 offer0=product_code:electronic_software^merchant_product_ sku:testdl^quantity:1^amount:1.56^tax_amount:0.25^product_ name:pname1^offer_id:0 request_id= ship_to_address1=37 se main street ship_to_address2=suite 2-5A ship_to_city=bloomington ship_to_country=us ship_to_state=indiana ship_to_zip=47404 Global Payment Service Developer Guide March

49 Chapter 3 Bank Transfers and Bank Transfer Refunds Using the SCMP API Standalone Bank Transfer Refund Reply Example 10 Standalone Bank Transfer Refund Reply bank_transfer_refund_amount=1.81 bank_transfer_refund_iban=ie64bofi bank_transfer_refund_rcode=1 bank_transfer_refund_rflag=sok bank_transfer_refund_rmsg=request was processed successfully. bank_transfer_refund_time= t213327z bank_transfer_refund_trans_ref_no= currency=eur ics_rcode=1 ics_rflag=sok ics_rmsg=request was processed successfully. merchant_ref_number=merref123 request_id= Follow-On Bank Transfer Refund Request Example 11 Follow-On Bank Transfer Refund Request ics_applications=ics_bank_transfer_refund bank_account_name=nette bank_account_number= bank_check_digit=12 bank_city=paris bank_code= bank_country=france bank_name=bnp Paribas bank_swiftcode=bnpa FR PP PLZ bank_transfer_request_id= bill_address1=1ere Avenue bill_address2=14eme Rue BP 148 bill_city=carros Cedex bill_country=fr bill_zip=06513 branch_code= abcde currency=eur customer_ [email protected] customer_firstname=antoi customer_lastname=nette customer_phone= merchant_id=mercid123 merchant_ref_number=merref123 offer0=product_code:electronic_software^merchant_product_ sku:testdl^quantity:1^amount:1.56^tax_amount:0.25^product_ name:pname1^offer_id:0 request_id= sender_id=gc_btr_sepa_1 Global Payment Service Developer Guide March

50 Chapter 3 Bank Transfers and Bank Transfer Refunds Using the SCMP API ship_to_address1=37 se main street ship_to_address2=suite 2-5A ship_to_city=bloomington ship_to_country=us ship_to_state=indiana ship_to_zip=47404 Follow-On Bank Transfer Refund Reply Example 12 Follow-On Bank Transfer Refund Reply bank_transfer_account_holder=global Collect BV bank_transfer_account_number= bank_transfer_amount=1.81 bank_transfer_bank_city=paris bank_transfer_bank_country=france bank_transfer_bank_name=bnp Paribas bank_transfer_iban=fr bank_transfer_payment_reference= bank_transfer_rcode=1 bank_transfer_rflag=sok bank_transfer_rmsg=request was processed successfully. bank_transfer_swiftcode=bnpa FR PP PLZ bank_transfer_time= t213323z Global Payment Service Developer Guide March

51 Real-Time Bank Transfers Using the Simple Order API CHAPTER 4 Transaction Status You can perform an on-demand query to get the status of a transaction. CyberSource recommends that you wait at least 5 minutes after the customer has completed a transaction before sending an on-demand query. If you need to request the status more than once, you must wait at least 10 minutes between queries for the same transaction. Note For China, real-time bank transfer settlements are not posted until the next business day. Sending the Query To send the query, send the fields described in the following table in an HTTP POST request to the following URL: After you send the query, CyberSource prompts you for your username and password to verify that you have access to the merchant ID. Table 11 Required Data for an On-Demand Transaction Status Query Field Description Required (R) or Optional (O) Data Type & Length merchantid Your CyberSource merchant ID. R String (30) type subtype requestid Type of query. The only possible value is transaction. Query subtype. The only possible value is transactionstatus. Request ID returned in the real-time bank transfer reply. R String (30) R String (30) R String (26) Global Payment Service Developer Guide March

52 Chapter 4 Real-Time Bank Transfers Using the Simple Order API Table 11 Required Data for an On-Demand Transaction Status Query (Continued) Field Description Required (R) or Optional (O) transrefno requesttoken Transaction reference number (SCMP API) or reconciliation ID (Simple Order API) returned in the real-time bank transfer reply. Request token data generated by CyberSource for each transaction reply. Data Type & Length R String (60) R String (256) This example shows an on-demand query for a transaction status. Example 13 On-Demand Transaction Status Query <html> <body> <form action=" method="post"> <input type="hidden" name="type" value="transaction"> <input type="hidden" name="subtype" value="transactionstatus"> <table> <tr> <td>merchant ID <font color=red>*</font>:</td> <td><input type="text" name="merchantid" value="dm_ptech"></td> </tr> <tr> <td>request ID: </td> <td><input type="text" name="requestid" value=""></td> </tr> <tr> <td>transaction Reference Number:</td> <td><input type="text" name="transrefno" value=""></td> </tr> <tr> <td>request Token:</td> <td><input type="text" name="requesttoken" value=""></td> </tr> <tr><td colspan=2> </td></tr> <tr><td colspan=2><input type="submit" value="submit"></td></tr> </table> </form> </body> </html> Global Payment Service Developer Guide March

53 Chapter 4 Real-Time Bank Transfers Using the Simple Order API Viewing the Response You receive a response immediately. There are two possible outcomes: If the query is successful, the results appear as a document of mime type application/ xml. To use this document, you must write a program to save or process the XML data of the document. If your POST data contains an error, you receive a system error. If the system error persists, contact CyberSource Customer Support. The DTD for a successful query result: <!ELEMENT xml (Request, Response)> <!ELEMENT Request (MerchantID, RequestID, RequestDate)> <!ELEMENT MerchantID (#PCDATA)> <!ELEMENT RequestID (#PCDATA)> <!ELEMENT RequestDate (#PCDATA)> <!ELEMENT Response (PaymentStatus?)> <!ELEMENT PaymentStatus (Status, ProcessorMessage?)> <!ELEMENT Status (#PCDATA)> <!ELEMENT ProcessorMessage (#PCDATA)> This example shows on-demand query results for a successful real-time bank transfer payment. Example 14 Successful Payment <xml> <Request> <MerchantID>okgo123</MerchantID> <RequestID> </RequestID> <RequestDate>Oct 30, 2014</RequestDate> <Response> <PaymentStatus> <Status>Payment</Status> <ProcessorMessage>The payment instruction has been accepted. </ProcessorMessage> </PaymentStatus> </Response> </Request> </xml> Global Payment Service Developer Guide March

54 Chapter 4 Real-Time Bank Transfers Using the Simple Order API This example shows on-demand query results for a failed real-time bank transfer payment. Example 15 Failed Payment <xml> <Request> <MerchantID>OKGo1234</MerchantID> <RequestID> </RequestID> <Response> <PaymentStatus> <Status>Failed</Status> <ProcessorMessage>Payment instruction has been rejected</processormessage> </PaymentStatus> </Response> </Request> </xml> Requesting Real-Time Bank Transfers To request a real-time bank transfer, set the banktransferrealtimeservice_run field to true. See Table 12, page 55, for a list of the fields to use when requesting the service. Table 14, page 61, describes the fields that the service returns to you. When requesting a real-time bank transfer, you may not request any other ICS service except Tax Calculation, which is optional. For more information about the service, see Tax Calculation Service Using the Simple Order API. Global Payment Service Developer Guide March

55 Chapter 4 Real-Time Bank Transfers Using the Simple Order API Requesting Real-Time Bank Transfer Refunds Important From August 1, 2016, for euro countries and from October 31, 2016, for noneuro countries, the IBAN must be included in each request. If you provide a BBAN it will be converted to an IBAN, and this conversion process will continue only until August 1, Except for a few additional fields, refunds for real-time bank transfers are the same as refunds for other bank transfers. See "Requesting Bank Transfer Refunds," page 16. The additional fields are identifiers that have been re-named for real-time bank transfers. See Table 15, page 63. API Fields For information about the data types, see Getting Started with CyberSource Advanced for the Simple Order API. Request Fields The following table lists the fields to use in a request for real-time bank transfers. Table 12 Request Fields for Real-Time Bank Transfers Using the Simple Order API Request Field Description Required (R) or Optional (O) bankinfo_bankcode Code for the customer s bank. Real-Time Bank Transfer (O) bankinfo_country banktransferrealtime Service_bankTransfer RealTimeType banktransferrealtime Service_run Country in which the bank is located. Use the two-character ISO Standard Country Codes. Code that indicates which payment method or bank to use for this transaction. See Table 13, page 60. Set to true to include the real-time bank transfer service in your request. Real-Time Bank Transfer (R) Real-Time Bank Transfer (R) Real-Time Bank Transfer (R) billto_city Billing address city. Real-Time Bank Transfer (R) billto_company Name of the customer s company. Real-Time Bank Transfer (O) Data Type & Length String (8) String (2) String (2) String (5) String (50) String (60) Global Payment Service Developer Guide March

56 Chapter 4 Real-Time Bank Transfers Using the Simple Order API Table 12 Request Fields for Real-Time Bank Transfers Using the Simple Order API (Continued) Request Field Description Required (R) or Optional (O) billto_country Billing address country. Real-Time Bank Transfer (R) billto_ Customer s address, including the full domain name. For example: [email protected] Real-Time Bank Transfer (R) billto_firstname Customer s first name. Real-Time Bank Transfer (R) billto_language Language used for the order. Use the ISO standard language codes. Real-Time Bank Transfer (O) billto_lastname Customer s last name. Real-Time Bank Transfer (R) billto_phonenumber Customer s telephone number. Real-Time Bank Transfer (O) billto_postalcode billto_state Postal code for the billing address. The postal code must consist of 5 to 9 digits. If the value of billto_country is US, the 9-digit postal code must follow this format: [5 digits][dash][4 digits] Example: If the value of billto_country is CA, the 6-digit postal code must follow this format: [alpha][numeric][alpha] [numeric][alpha][numeric] Example: A1B 2C3 Billing address state. This field is required if the billto_country value is US or CA. Real-Time Bank Transfer (R if billing country is US or CA) Real-Time Bank Transfer (See billto_street1 Billing address street address. Real-Time Bank Transfer (R) billto_street2 Additional address information. Real-Time Bank Transfer (O) fundtransfer_ accountnumber fundtransfer_iban Customer s bank account number. International Bank Account Number (IBAN) for the bank account. Note Required for specific countries. Contact CyberSource Customer Support for required country-specific. Real-Time Bank Transfer (O) Real-Time Bank Transfer (See Data Type & Length String (2) String (255) String (60) String (2) String (60) String (15) String (10) String (2) String (60) String (60) String (10) String (30) Global Payment Service Developer Guide March

57 Chapter 4 Real-Time Bank Transfers Using the Simple Order API Table 12 Request Fields for Real-Time Bank Transfers Using the Simple Order API (Continued) Request Field Description Required (R) or Optional (O) invoiceheader_ merchantdescriptor item_#_productcode item_#_productname item_#_productsku item_#_quantity Merchant descriptor that is displayed on the customer s statement for each real-time bank transfer. To enable this field and to optionally set a default descriptor for all real-time bank transfers, contact CyberSource Customer Support. Type of product. This value is used to determine the product category: electronic, handling, physical, service, or shipping. The default value is default. See "Product Codes," page 154, for a list of valid values. If you set it to a value other than default, stored_value, or any of the values related to shipping and/or handling, the item_#_ quantity, item_#_product_name, and item_#_ productsku fields are required. Name of the product. This field is required if item_#_productcode is not default, stored_value, or one of the values related to shipping and/or handling. Product identifier code. It is required if item_#_ productcode is not default, stored_ value, or one of the values related to shipping and/or handling. Quantity of the product being purchased. The default value is 1. This field is required if item_ #_productcode is not default, stored_ value, or one of the values related to shipping and/or handling. Real-Time Bank Transfer (O) Real-Time Bank Transfer (O) Real-Time Bank Transfer (See Real-Time Bank Transfer (See Real-Time Bank Transfer (See Data Type & Length String (50) For ideal: String (32) String (30) String (30) String (30) Integer (10) Global Payment Service Developer Guide March

58 Chapter 4 Real-Time Bank Transfers Using the Simple Order API Table 12 Request Fields for Real-Time Bank Transfers Using the Simple Order API (Continued) Request Field Description Required (R) or Optional (O) item_#_taxamount Tax amount associated with this item. This field is additive. For example, if you send these offer lines: offer0=amount:10.00^ quantity:1^tax_amount:0.80 offer1=amount:20.00^ quantity:1^tax_amount:1.60 Real-Time Bank Transfer (O) Data Type & Length String (15) the total amount authorized will be for 32.40, not with 2.40 of tax included. The item_#_taxamount and the item_#_ unitprice values must be in the same currency. If you include item_#_taxamount and you include taxservice in your request, taxservice does not calculate the tax for the offer. Instead, it returns the value in the item_#_taxamount field. item_#_unitprice Per-item price of the product. You must include either this field or the purchasetotals_ grandtotalamount field in your request. This value cannot be negative. See the information about items and grand totals in Getting Started with CyberSource Advanced for the Simple Order API. Real-Time Bank Transfer (See String (15) You can include a decimal point (.) in this field, but you cannot include any other special characters. The amount will be truncated at the request level to the correct number of decimal places. linktorequest Value that links the current request to a previous authorization request for a debit card or prepaid card. This value is useful when using multiple payment methods to complete an order. For more information about partial authorizations, see Credit Card Services Using the Simple Order API. Real-Time Bank Transfer (O) merchantid Your CyberSource merchant ID. Real-Time Bank Transfer (R) merchantreferencecode Merchant-generated order reference or tracking number. If this field includes multi-byte characters, it might be corrupted when it is returned to you in the reply. For more information about tracking orders, see Getting Started with CyberSource Advanced for the Simple Order API. Real-Time Bank Transfer (R) String (26) String (30) String (50) Global Payment Service Developer Guide March

59 Chapter 4 Real-Time Bank Transfers Using the Simple Order API Table 12 Request Fields for Real-Time Bank Transfers Using the Simple Order API (Continued) Request Field Description Required (R) or Optional (O) purchasetotals_currency purchasetotals_ grandtotalamount returnurl shipto_city shipto_country Currency used for the order. Use the ISO Standard Currency Codes. Grand total for the order. You must include either this field or item_#_unitprice in your request. For more information about items and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API. URL that returns the customer to your Web site after the transaction. You are required to provide this value using one of the following methods: Send this field with every request. Provide the URL when you register for the service, and CyberSource will store it in a database. City of shipping address. This field is required if any shipping information is included in the request. Country of shipping address. Use the twocharacter ISO Standard Country Codes. Real-Time Bank Transfer (R) Real-Time Bank Transfer (See Real-Time Bank Transfer (See Real-Time Bank Transfer (See Real-Time Bank Transfer (O) shipto_firstname First name of the person receiving the product. Real-Time Bank Transfer (O) shipto_lastname Last name of the person receiving the product. Real-Time Bank Transfer (O) shipto_phonenumber Phone number for the shipping address. Real-Time Bank Transfer (O) shipto_postalcode Postal code for the shipping address. The postal code must consist of 5 to 9 digits. If the value of shipto_country is US, the 9-digit postal code must follow these rules: [5 digits][dash][4 digits] Example: If the value of shipto_country is CA, the 6-digit postal code must follow these rules: [alpha][numeric][alpha] [numeric][alpha][numeric] Example: A1B 2C4 If the postal code for the shipping address is not included in the request message, CyberSource uses the postal code from the billing address. If the postal code for the billing address is not included in the request message, the postal code for the shipping address is required. Real-Time Bank Transfer (R if shipto_country is US or CA) Data Type & Length String (5) String (15) String (512) String (50) String (2) String (60) String (60) String (15) String (10) Global Payment Service Developer Guide March

60 Chapter 4 Real-Time Bank Transfers Using the Simple Order API Table 12 Request Fields for Real-Time Bank Transfers Using the Simple Order API (Continued) Request Field Description Required (R) or Optional (O) shipto_state shipto_street1 State or province of shipping address. Use the State, Province, and Territory Codes for the United States and Canada. This field is required if the shipto_country value is US or CA. First line of shipping address. This field is required if any shipping information is included in the request. Real-Time Bank Transfer (See Real-Time Bank Transfer (See shipto_street2 Second line of shipping address. Real-Time Bank Transfer (O) Data Type & Length String (2) String (60) String (60) Bank Codes The following table describes the bank codes that indicate the payment method or bank to use for a real-time bank transfer. Table 13 Bank Transfer Real Time Type Bank Code Bank or Payment Type Country Bank or Network 1 ING Home Pay Belgium Single bank 2 Nordea e-maksu Finland Single bank 3 Nordea e-betaling Denmark Single bank 5 Nordea e-betalning Sweden Single bank 7 ideal Netherlands Banking network. The customer selects the specific bank on your payment page. 9 GiroPay Germany Banking network. The customer selects the specific bank on a web page that you do not control. 11 ecard Poland Banking network. The customer selects the specific bank on a web page that you do not control. 12 enets Singapore Banking network. The customer selects the specific bank on a web page that you do not control. 17 Akita Finland Banking network. The customer selects the specific bank on a web page that you do not control. 18 Sofortuberweisung Germany Banking network. The customer selects the specific bank on a web page that you do not control. Global Payment Service Developer Guide March

61 Chapter 4 Real-Time Bank Transfers Using the Simple Order API Table 13 Bank Transfer Real Time Type (Continued) Bank Code Bank or Payment Type Country Bank or Network 20 Poli Australia Banking network. The customer selects the specific bank on a web page that you do not control. Reply Fields The following table lists the fields returned in a reply from the banktransferrealtimeservice service request. Table 14 Reply Fields for Real-Time Bank Transfers Using the Simple Order API Reply Field Description Data Type & Length banktransferrealtimereply_ amount Total amount for the real-time bank transfer. String (15) banktransferrealtimereply_ formaction banktransferrealtimereply_ formmethod banktransferrealtimereply_ paymentreference banktransferrealtimereply_ reasoncode banktransferrealtimereply_ reconciliationid banktransferrealtimereply_ requestdatetime banktransferrefundreply_iban URL that will be used to re-direct the customer s browser window back to your web site. Method that redirects the customer s browser window to your web site. The possible values are: GET POST Payment reference number that you must display to the customer. For more information about tracking orders, see Getting Started with CyberSource Advanced for the Simple Order API. In Italy, this number is called the Numero di riferimento. A numeric value corresponding to the result of the real-time bank transfer request. See "Reason Codes," page 155, for a list of possible values. Unique value generated by CyberSource. See the information about tracking orders in Getting Started with CyberSource Advanced for the Simple Order API. Time the real-time bank transfer was requested. Format: YYYY-MM-DDThh:mm:ssZ. Example: T22:47:57Z, which is August 11, 2007, at 10:47:57 P.M. The T separates the date and the time. The Z indicates UTC. International Bank Account Number (IBAN) for the bank account. String (4000) String (4) String (16) Integer (5) String (60) String (20) Alphanumeric (50) Global Payment Service Developer Guide March

62 Chapter 4 Real-Time Bank Transfers Using the Simple Order API Table 14 Reply Fields for Real-Time Bank Transfers Using the Simple Order API (Continued) Reply Field Description Data Type & Length decision Summarizes the result of the overall request. The possible values are: ACCEPT ERROR REJECT String (6) invalidfield_0...n merchantreferencecode missingfield_0...n purchasetotals_currency reasoncode Fields in the request that contained invalid data. These reply fields are included as an aid to software developers only. Note Do not attempt to use these fields for interacting with end users. For more information about missing and invalid fields, see Getting Started with CyberSource Advanced for the Simple Order API. Order reference or tracking number that you provided in the request. If you included multi-byte characters in this field in the request, the returned value might contain corrupted characters. Required fields that were missing from the request. These reply fields are included as an aid to software developers only. Note Do not attempt to use these fields for interacting with end users. For more information about missing and invalid fields, see Getting Started with CyberSource Advanced for the Simple Order API. Currency used for the order. Use the ISO Standard Currency Codes. Numeric value corresponding to the result of the overall request. See "Reason Codes," page 155, for a list of possible values. String (100) String (50) String (100) String (5) Integer (5) requestid Identifier for the request generated by CyberSource. String (26) requesttoken Request token data created by CyberSource for each reply. The field is an encoded string that contains no confidential information such as an account number. The string can contain a maximum of 256 characters. String (256) Global Payment Service Developer Guide March

63 Chapter 4 Real-Time Bank Transfers Using the Simple Order API Additional Request Fields The following table lists the additional fields to use in a request for the banktransferrefundservice service. In addition to these fields, you must use the fields specified for refunds in "Request Fields," page 18. Table 15 Additional Request Fields for Bank Transfer Refunds for the Simple Order API Request Field Description Required (R) or Optional (O) banktransferrefund Service_bankTransfer RealTimeReconciliationID banktransferrefund Service_bankTransfer RealTimeRequestID Unique identifier for the order submitted to Global Collect. Note If you do not include this field in a refund request, CyberSource will generate the value. The requestid field returned from a previous request for the banktransferrealtimeservice service. Send this field instead of the banktransferrefundservice_ banktransferrequestid field. Bank Transfer Refund (R for standalone refunds) Bank Transfer Refund (R) Data Type & Length String (60) String (26) Global Payment Service Developer Guide March

64 Chapter 4 Real-Time Bank Transfers Using the Simple Order API Request and Reply Examples Real-Time Bank Transfer Request Example 16 Real-Time Bank Transfer Request <requestmessage xmlns="urn:schemas-cybersource-com:transaction-data-1.23"> <banktransferrealtimeservice run="true"/> <merchantid>demo</merchantid> <merchantreferencecode>482046</merchantreferencecode> <billto> <firstname>john</firstname> <lastname>smith</lastname> <street1>boschdijk 987</street1> <city>eindhoven</city> <country>nl</country> <language>nl</language> <postalcode>5600 PB</postalCode> < >[email protected]</ > <phonenumber> </phonenumber> </billto> <purchasetotals> <currency>eur</currency> </purchasetotals> <item id="0"> <unitprice>49.95</unitprice> <quantity>1</quantity> </item> <banktransferrealtimeservice> <banktransferrealtimetype>7</banktransferrealtimetype> </banktransferrealtimeservice> <bankinfo> <country>nl</country> </bankinfo> </requestmessage> Global Payment Service Developer Guide March

65 Chapter 4 Real-Time Bank Transfers Using the Simple Order API Real-Time Bank Transfer Reply Example 17 Real-Time Bank Transfer Reply <c:replymessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.23"> <c:requestid> </c:requestid> <c:merchantreferencecode>482046</c:merchantreferencecode> <c:purchasetotals> <c:currency>eur</c:currency> </c:purchasetotals> <c:decision>accept</c:decision> <c:reasoncode>100</c:reasoncode> <c:banktransferrealtimereply> <c:reconciliationid> </c:reconciliationid> <c:amount>49.95</c:amount> <c:requestdatetime> t23:44:27z</c:requestdatetime> <c:paymentreference> </c:paymentreference> <c:reasoncode>100</c:reasoncode> <c:formmethod>get</c:formmethod> <c:formaction> </c:banktransferrealtimereply> </c:replymessage> Example 18 Real-Time Bank Transfer Refund Real-Time Bank Transfer Refund Request <requestmessage xmlns="urn:schemas-cybersource-com:transaction-data-1.103"> <merchantid>demo123</merchantid> <merchantreferencecode>demoref</merchantreferencecode> <billto> <firstname>orlando</firstname> <lastname>bloom</lastname> <street1>33, rue Dauphine</street1> <city>bergheim</city> <postalcode>75006</postalcode> <country>de</country> <phonenumber> </phoneNumber> < >[email protected]</ > </billto> <purchasetotals> <currency>eur</currency> <grandtotalamount>74</grandtotalamount> </purchasetotals> <fundtransfer> <accountnumber> </accountnumber> <accountname>bradford NICKLES</accountName> </fundtransfer> Global Payment Service Developer Guide March

66 Chapter 4 Real-Time Bank Transfers Using the Simple Order API <bankinfo> <bankcode> </bankcode> <name>sloveniabank_testing</name> <country>de</country> <swiftcode>bsljsi2x</swiftcode> </bankinfo> <banktransferrefundservice run="true"> <reconciliationid> </reconciliationid> </banktransferrefundservice> </requestmessage> Example 19 Real-Time Bank Transfer Refund Reply Real-Time Bank Transfer Refund Reply <c:replymessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.103"> <c:merchantreferencecode>demoref</c:merchantreferencecode> <c:requestid> </c:requestid> <c:decision>accept</c:decision> <c:reasoncode>100</c:reasoncode> <c:purchasetotals> <c:currency>eur</c:currency> </c:purchasetotals> <c:banktransferrefundreply> <c:reasoncode>100</c:reasoncode> <c:amount>74.00</c:amount> <c:requestdatetime> t23:33:08z</c:requestdatetime> <c:reconciliationid> </c:reconciliationid> <c:iban>de </c:iban> </c:banktransferrefundreply> </c:replymessage> Global Payment Service Developer Guide March

67 Real-Time Bank Transfers Using the SCMP API CHAPTER 5 Transaction Status You can perform an on-demand query to get the status of a transaction. CyberSource recommends that you wait at least 5 minutes after the customer has completed a transaction before sending an on-demand query. If you need to request the status more than once, you must wait at least 10 minutes between queries for the same transaction. Note For China, real-time bank transfer settlements are not posted until the next business day. Sending the Query To send the query, send the fields described in the following table in an HTTP POST request to the following URL: After you send the query, CyberSource will prompt you for your username and password to verify that you have access to the merchant ID. Table 16 Required Data for the On-Demand Transaction Status Query Field Description Required (R) or Optional (O) Data Type & Length merchantid Your CyberSource merchant ID. R String (30) type subtype requestid transrefno Type of query. The only possible value is transaction. Query subtype. The only possible value is transactionstatus. Request ID returned in the real-time bank transfer reply. Transaction reference number (SCMP API) or reconciliation ID (Simple Order API) returned in the real-time bank transfer reply. R String (30) R String (30) R String (26) R String (60) Global Payment Service Developer Guide March

68 Chapter 5 Real-Time Bank Transfers Using the SCMP API Table 16 Required Data for the On-Demand Transaction Status Query (Continued) Field Description Required (R) or Optional (O) requesttoken Request token data generated by CyberSource for each transaction reply. Data Type & Length R String (256) This example shows an on-demand query for a transaction s status: Example 20 On-Demand Transaction Status Query <html> <body> <form action=" method="post"> <input type="hidden" name="type" value="transaction"> <input type="hidden" name="subtype" value="transactionstatus"> <table> <tr> <td>merchant ID <font color=red>*</font>: </td> <td><input type="text" name="merchantid" value="dm_ptech"></td> </tr> <tr> <td>request ID: </td> <td><input type="text" name="requestid" value=""></td> </tr> <tr> <td>transaction Reference Number: </td> <td><input type="text" name="transrefno" value=""></td> </tr> <tr> <td>request Token: </td> <td><input type="text" name="requesttoken" value=""></td> </tr> <tr><td colspan=2> </td></tr> <tr><td colspan=2><input type="submit" value="submit"></td></tr> </table> </form> </body> </html> Global Payment Service Developer Guide March

69 Chapter 5 Real-Time Bank Transfers Using the SCMP API Viewing the Response You receive a response immediately. There are two possible outcomes: If the query is successful, the results appear as a document of mime type application/ xml. To use this document, you need to write a program to save or process the XML data of the document. If your POST data contains an error, you receive a system error. If the system error persists, contact CyberSource Customer Support. The DTD for a successful query result: <!ELEMENT xml (Request, Response)> <!ELEMENT Request (MerchantID, RequestID)> <!ELEMENT MerchantID (#PCDATA)> <!ELEMENT RequestID (#PCDATA)> <!ELEMENT Response (PaymentStatus?)> <!ELEMENT PaymentStatus (Status, ProcessorMessage?)> <!ELEMENT Status (#PCDATA)> <!ELEMENT ProcessorMessage (#PCDATA)> This example shows on-demand query results for a successful real-time bank transfer payment: Example 21 Successful Payment <xml> <Request> <MerchantID>OKGo1234</MerchantID> <RequestID> </RequestID> <Response> <PaymentStatus> <Status>Payment</Status> </PaymentStatus> </Response> </Request> </xml> Global Payment Service Developer Guide March

70 Chapter 5 Real-Time Bank Transfers Using the SCMP API This example shows on-demand query results for a failed real-time bank transfer payment: Example 22 Failed Payment <xml> <Request> <MerchantID>OKGo1234</MerchantID> <RequestID> </RequestID> <Response> <PaymentStatus> <Status>Failed</Status> <ProcessorMessage>Payment instruction has been rejected</processormessage> </PaymentStatus> </Response> </Request> </xml> Requesting Real-Time Bank Transfers Use the ics_bank_transfer_real_time service to request a real-time bank transfer. See Table 17, page 71, and Table 18, page 75, for fields to use when requesting the service. Table 20, page 78, describes the fields that the service returns to you. When requesting a real-time bank transfer, you may not request any of the other ICS services except ics_tax, which is optional. For more information about the service, see Tax Calculation Service Using the SCMP API. Global Payment Service Developer Guide March

71 Chapter 5 Real-Time Bank Transfers Using the SCMP API Requesting Real-Time Bank Transfer Refunds Important From August 1, 2016, for euro countries and from October 31, 2016, for noneuro countries, the IBAN must be included in each request. If you provide a BBAN it will be converted to an IBAN, and this conversion process will continue only until August 1, Except for a few additional fields, refunds for real-time bank transfers are the same as refunds for traditional bank transfers. See "Requesting Bank Transfer Refunds," page 34. The additional fields are identifiers that have been re-named for real-time bank transfers. See Table 22, page 80. API Fields For information about the data types, see Getting Started with CyberSource Advanced for the SCMP API. Request Fields The following table lists the fields to use in a request for the ics_bank_transfer_real_ time field. Table 17 Request-Level Fields for Real-Time Bank Transfers Using the SCMP API Request-Level Field Description Required (R) or Optional (O) bank_account_number Customer s bank account number. Real-Time Bank Transfer (O) bank_code Code for the customer s bank. Real-Time Bank Transfer (O) bank_country bank_iban Country where the bank is located. Use the two-character ISO Standard Country Codes. International Bank Account Number (IBAN) for the bank account. Note Required for specific countries. Contact CyberSource Customer Support for required country-specific requirements. Real-Time Bank Transfer (R) Real-Time Bank Transfer (See Data Type & Length String (10) String (8) String (2) String (30) Global Payment Service Developer Guide March

72 Chapter 5 Real-Time Bank Transfers Using the SCMP API Table 17 Request-Level Fields for Real-Time Bank Transfers Using the SCMP API (Continued) Request-Level Field Description Required (R) or Optional (O) bank_transfer_real_time_ type Code that indicates the payment method or bank to use for this transaction. See Table 19, page 76. Real-Time Bank Transfer (R) bill_address1 Billing street address. Real-Time Bank Transfer (R) bill_address2 Additional billing address information. Real-Time Bank Transfer (O) bill_city Billing address city. Real-Time Bank Transfer (R) bill_country Billing address country. Real-Time Bank Transfer (R) bill_state bill_zip Billing address state. This field is required if the value of bill_country is US or CA. Zip code for the shipping address. The zip code must consist of 5 to 9 digits. If the value of bill_country is US, the 9-digit zip code must follow this format: [5 digits][dash][4 digits] Example: If the value of bill_country is CA, the 6-digit zip code must follow this format: [alpha][numeric][alpha] [numeric][alpha][numeric] Example: A1B 2C3 Real-Time Bank Transfer (See Real-Time Bank Transfer (R if bill_ country is US or CA) company_name Name of the customer s company. Real-Time Bank Transfer (O) currency customer_ Currency used for the order. Use the ISO Standard Currency Codes. Customer s address. For example: [email protected] Real-Time Bank Transfer (R) Real-Time Bank Transfer (R) customer_firstname Customer s first name. Real-Time Bank Transfer (R) customer_language Language used for the order. Use the ISO standard language codes. Real-Time Bank Transfer (O) customer_lastname Customer s last name. Real-Time Bank Transfer (R) customer_phone Customer s telephone number. Real-Time Bank Transfer (O) Data Type & Length String (2) String (60) String (60) String (50) String (2) String (2) String (10) String (60) String (5) String (255) String (60) String (2) String (60) String (15) Global Payment Service Developer Guide March

73 Chapter 5 Real-Time Bank Transfers Using the SCMP API Table 17 Request-Level Fields for Real-Time Bank Transfers Using the SCMP API (Continued) Request-Level Field Description Required (R) or Optional (O) grand_total_amount Grand total for the order. You must include either this field or offer0 and the offer-level field amount. See the information about offers and grand totals in Getting Started with CyberSource Advanced for the SCMP API. Real-Time Bank Transfer (See ics_applications ICS services to process for the request. Real-Time Bank Transfer (R) link_to_request merchant_descriptor Value that links the current request to a previous authorization request for a debit card or prepaid card. This value is useful when using multiple payment methods to complete an order. For details, see the information about partial authorizations in Credit Card Services Using the SCMP API. Merchant descriptor that is displayed on the customer s statement for each real-time bank transfer. To enable this field and to optionally set a default descriptor for all real-time bank transfers, contact CyberSource Customer Support. Real-Time Bank Transfer (O) Real-Time Bank Transfer (O) merchant_id Your CyberSource merchant ID. Real-Time Bank Transfer (R) merchant_ref_number offer0...n return_url ship_to_address1 Merchant-generated order reference or tracking number. If this field includes multi-byte characters, it might be corrupted when it is returned to you in the reply. See the information about tracking orders in Getting Started with CyberSource Advanced for the SCMP API. Offers for the request. An offer is a line item for the order. URL that will be used to return the customer to your web site after the transaction. You are required to provide this value using one of the following methods: Send this field with every request. Provide the URL when you sign up for the service, and CyberSource will store it in a database. First line of the address to which the product will be shipped. This field is required if any shipping information is included in the request. Real-Time Bank Transfer (R) Real-Time Bank Transfer (O) Real-Time Bank Transfer (See Real-Time Bank Transfer (See Data Type & Length Decimal (15) String (255) String (26) String (50) For ideal: String (32) String (30) String (50) String (50) String (512) String (60) Global Payment Service Developer Guide March

74 Chapter 5 Real-Time Bank Transfers Using the SCMP API Table 17 Request-Level Fields for Real-Time Bank Transfers Using the SCMP API (Continued) Request-Level Field Description Required (R) or Optional (O) ship_to_address2 ship_to_city ship_to_country Second line of the address to which the product will be shipped. City to which the product will be shipped. This field is required if any shipping information is included in the request. Country to which the product will be shipped. Use the two-character ISO Standard Country Codes. Real-Time Bank Transfer (O) Real-Time Bank Transfer (See Real-Time Bank Transfer (O) ship_to_firstname First name of person receiving the product. Real-Time Bank Transfer (O) ship_to_lastname Last name of person receiving the product. Real-Time Bank Transfer (O) ship_to_phone Phone number for the shipping address. Real-Time Bank Transfer (O) ship_to_state ship_to_zip timeout State or province to which the product will be shipped. Use the State, Province, and Territory Codes for the United States and Canada. This field is required if the value ship_to_country is US or CA. Zip code for the shipping address. If the value of ship_to_country is US, the 9- digit zip code must follow this format: [5 digits][dash][4 digits] Example: If the value of ship_to_country is CA, the 6- digit zip code must follow this format: [alpha][numeric][alpha] [numeric][alpha][numeric] Example: A1B 2C3 If the postal code for the shipping address is not included in the request message, CyberSource will use the postal code for the billing address. If the postal code for the billing address is not included in the request message, the postal code for the shipping address is required. Number of seconds until the transaction times out. The default is 110 seconds. Real-Time Bank Transfer (See Real-Time Bank Transfer (R is if ship_to_country is US or CA) Real-Time Bank Transfer (O) Data Type & Length String (60) String (50) String (2) String (60) String (60) String (15) String (2) String (10) Positive integer (3) Global Payment Service Developer Guide March

75 Chapter 5 Real-Time Bank Transfers Using the SCMP API Offer-Level Fields The following table lists the offer-level fields for the ics_bank_transfer_real_time field. Table 18 Offer-Level Fields for Real-Time Bank Transfers for the SCMP API Offer-Level Field Description Required (R) or Optional (O) amount merchant_product_sku product_code product_name quantity Per-item price of the product. You must include either offer0 and this field, or the request-level field grand_total_amount in your request. This value cannot be negative. See the information about offers and grand totals in Getting Started with CyberSource Advanced for the SCMP API. You can include a decimal point (.) in this field, but you cannot include any other special characters. The amount will be truncated at the request level to the correct number of decimal places. Product identifier code. It is required if product_code is not default, stored_ value, or one of the values related to shipping and/or handling. Type of product the offer contains. This value is used to determine the category that the product falls under: electronic, handling, physical, service, or shipping. The default value is default. See "Product Codes," page 154, for a list of valid values. If you set this to a value other than default, stored_value, or any of the values related to shipping and/or handling, the quantity, product_name and merchant_product_sku fields are required. Name of the product. This field is required if product_code is not default, stored_ value or one of the values related to shipping and/or handling. Quantity of the product being purchased. The default value is 1. This field is required if product_code is not default, stored_ value or one of the values related to shipping and/or handling. Real-Time Bank Transfer (See Real-Time Bank Transfer (See Real-Time Bank Transfer (O) Real-Time Bank Transfer (See Real-Time Bank Transfer (See Data Type & Length Decimal (15) String (30) String (30) String (30) Nonnegative integer (10) Global Payment Service Developer Guide March

76 Chapter 5 Real-Time Bank Transfers Using the SCMP API Table 18 Offer-Level Fields for Real-Time Bank Transfers for the SCMP API (Continued) Offer-Level Field Description Required (R) or Optional (O) Data Type & Length tax_amount Tax amount associated with this item. This field is additive. For example, if you send these offer lines: Real-Time Bank Transfer (O) Decimal (15) offer0=amount:10.00^ quantity:1^tax_amount:0.80 offer1=amount:20.00^ quantity:1^tax_amount:1.60 the total amount authorized will be for 32.40, not with 2.40 of tax included. The tax_amount and the amount values must be in the same currency. If you include tax_amount and you request the ics_tax service, ics_tax will not calculate tax for the offer. Instead, it will return the value in the tax_amount field. Bank Codes The following table describes the values for the bank transfer real-time type. Table 19 Bank Transfer Real-Time Type Bank Code Bank or Payment Type Country Bank or Network 1 ING Home Pay Belgium Single bank 2 Nordea e-maksu Finland Single bank 3 Nordea e-betaling Denmark Single bank 5 Nordea e-betalning Sweden Single bank 7 ideal Netherlands Banking network. The customer selects the specific bank on your payment page. 9 GiroPay Germany Banking network. The customer selects the specific bank on a web page that you do not control. 11 ecard Poland Banking network. The customer selects the specific bank on a web page that you do not control. 12 enets Singapore Banking network. The customer selects the specific bank on a web page that you do not control. Global Payment Service Developer Guide March

77 Chapter 5 Real-Time Bank Transfers Using the SCMP API Table 19 Bank Transfer Real-Time Type (Continued) Bank Code 17 Akita Finland Banking network. The customer selects the specific bank on a web page that you do not control. 18 Sofortuberweisung Germany Banking network. The customer selects the specific bank on a web page that you do not control. 20 Poli Australia Banking network. The customer selects the specific bank on a web page that you do not control. Bank Code Bank or Payment Type Bank or Payment Type Country Country Bank or Network Bank or Network 1 ING Home Pay Belgium Single bank 2 Nordea e-maksu Finland Single bank 3 Nordea e-betaling Denmark Single bank 5 Nordea e-betalning Sweden Single bank 7 ideal Netherlands Banking network. The customer selects the specific bank on your payment page. Global Payment Service Developer Guide March

78 Chapter 5 Real-Time Bank Transfers Using the SCMP API Reply Fields The following table lists the fields returned in a reply from the ics_bank_transfer_real_ time request. Table 20 Reply Fields for Real-Time Bank Transfers Using the SCMP API Reply Field Description Data Type & Length bank_transfer_refund_iban International Bank Account Number (IBAN) for the bank account. Alphanumeric (50) bank_transfer_real_time_amount Total amount for the real-time bank transfer. Decimal (15) bank_transfer_real_time_form_ action bank_transfer_real_time_form_ method URL that will be used to re-direct the customer s browser window back to your web site. Method that will be used to re-direct the customer s browser window back to your web site. The possible values are: GET POST String (4000) String (4) bank_transfer_real_time_ payment_reference bank_transfer_real_time_rcode bank_transfer_real_time_rflag bank_transfer_real_time_rmsg bank_transfer_real_time_time bank_transfer_real_time_trans_ ref_no client_lib_version currency ics_rcode Payment reference number that you must display to the customer. See the information about tracking orders in Getting Started with CyberSource Advanced for the SCMP API. In Italy, this is called the Numero di riferimento. One-digit code that indicates whether the ics_bank_ transfer_real_time request was successful. One-word description of the result of the ics_bank_ transfer_real_time request. Message that explains the reply flag bank_transfer_real_ time_rflag. Time of the real-time bank transfer request in UTC. For the format, see the information about data types in Getting Started with CyberSource Advanced for the SCMP API. Unique value generated by CyberSource. See the information about tracking orders in Getting Started with CyberSource Advanced for the SCMP API. Information about the client library used to request the transaction. Currency used for the order. Use the ISO Standard Currency Codes. One-digit code that indicates whether the entire request was successful. The possible values are: -1: An error occurred 0: The request was declined 1: The request was successful String (16) Integer (1) String (50) String (255) Date and time (20) String (60) String (50) String (5) Integer (1) ics_rflag One-word description of the result of the entire request. String (50) Global Payment Service Developer Guide March

79 Chapter 5 Real-Time Bank Transfers Using the SCMP API Table 20 Reply Fields for Real-Time Bank Transfers Using the SCMP API (Continued) Reply Field Description Data Type & Length ics_rmsg Message that explains the reply flag ics_rflag. String (255) merchant_ref_number Order reference or tracking number that you provided in the request. If you included multi-byte characters in this field in the request, the returned value might contain corrupted characters. String (50) request_id Identifier for the request generated by CyberSource. String (26) request_token Request token data created by CyberSource for each reply. The field is an encoded string that contains no confidential information such as an account number. The string can contain a maximum of 256 characters. String (256) Reply Flags The following table lists the reply flags for the ics_bank_transfer_real_time request. Table 21 Reply Flags for Real-Time Bank Transfers for the SCMP API Reply Flag DINVALIDDATA DMISSINGFIELD ESYSTEM ETIMEOUT SOK Description Data provided is not consistent with the request. The request is missing a required field. System error. You must design your transaction management system to correctly handle CyberSource system errors. Depending on the payment processor handling the transaction, the error may indicate a valid CyberSource system error or a processor rejection due to invalid data. In either case, CyberSource recommends that you do not design your system to endlessly retry sending a transaction. For important information on handling system errors and retries, see the documentation for your CyberSource client. The request timed out. The transaction was successful. Global Payment Service Developer Guide March

80 Chapter 5 Real-Time Bank Transfers Using the SCMP API Additional Request Fields The following table lists the additional fields to use in a request for the ics_bank_ transfer_refund service. In addition to these fields, you must use the fields specified for refunds in "Request Fields," page 36. Table 22 Additional Request Fields for Bank Transfer Refunds Using the SCMP API Request Field Description Required (R) or Optional (O) bank_transfer_real_time_ request_id bank_transfer_real_time_ trans_ref_no The request_id value returned from a previous request for the ics_bank_ transfer_real_time service. Send this field instead of the bank_transfer_request_id field. Unique identifier for the order submitted to Global Collect. Note If you do not include this field in a refund request, CyberSource will generate the value. Bank Transfer Refund (R) Bank Transfer Refund (R for standalone refunds) Data Type & Length String (26) String (60) Global Payment Service Developer Guide March

81 Chapter 5 Real-Time Bank Transfers Using the SCMP API Request and Reply Examples Real-Time Bank Transfer Request Example 23 Real-Time Bank Transfer Request ics_applications=ics_bank_transfer_real_time bank_country=nl bank_transfer_real_time_type=12 bill_address1=1276vicentedrapth bill_city=eindhoven bill_country=nl bill_zip=5600 PB currency=eur customer_ [email protected] customer_firstname =john customer_lastname=smith customer_language=nl grand_total_amount=10.00 merchant_id=demo merchant_ref_number=c c Real-Time Bank Transfer Reply Example 24 Real-Time Bank Transfer Reply request_id= merchant_ref_number=c c currency=eur ics_rcode=1 ics_rflag=sok ics_rmsg=request was processed successfully. bank_transfer_real_time_trans_ref_no= bank_transfer_real_time_amount=10.00 bank_transfer_real_time_time= t170910z bank_transfer_real_time_payment_reference= bank_transfer_real_time_rcode=1 bank_transfer_real_time_rflag=sok bank_transfer_real_time_rmsg=request was processed successfully. bank_transfer_real_time_form_method=get Global Payment Service Developer Guide March

82 Chapter 5 Real-Time Bank Transfers Using the SCMP API Real-Time Bank Transfer Refund Request Example 25 Real-Time Bank Transfer Refund Request bank_account_name=nette bank_account_number= bank_check_digit=12 bank_city=paris bank_code= bank_country=france bank_name=bnp Paribas bank_swiftcode=bnpa FR PP PLZ bank_transfer_real_time_request_id= bill_address1=1ere Avenue bill_address2=14eme Rue BP 148 bill_city=carros Cedex bill_country=fr bill_zip=06513 branch_code= abcde currency=eur customer_ [email protected] customer_firstname=antoi customer_lastname=nette customer_phone= ics_applications=ics_bank_transfer_refund merchant_id=demo merchant_ref_number=c c offer0=product_code:electronic_software^merchant_product_ sku:testdl^quantity:1^amount:1.56^tax_amount:0.25^product_ name:pname1^offer_id:0 ship_to_address1=37 se main street ship_to_address2=suite 2-5A ship_to_city=bloomington ship_to_country=us ship_to_state=indiana ship_to_zip=47404 Global Payment Service Developer Guide March

83 Chapter 5 Real-Time Bank Transfers Using the SCMP API Real-Time Bank Transfer Refund Reply Example 26 Real-Time Bank Transfer Refund Reply bank_transfer_refund_amount=1.81 bank_transfer_refund_iban=ie64bofi bank_transfer_refund_rcode=1 bank_transfer_refund_rflag=sok bank_transfer_refund_rmsg=request was processed successfully. bank_transfer_refund_time= t213332z bank_transfer_refund_trans_ref_no= currency=eur ics_rcode=1 ics_rflag=sok ics_rmsg=request was processed successfully. merchant_ref_number=c c request_id= Global Payment Service Developer Guide March

84 Boletos Bancários Using the Simple Order API CHAPTER 6 Requesting a Boleto Bancário Use the boletopaymentservice service to request the Boleto Bancário payment service. See Table 23, page 85, for a list of the fields to use. In the Boleto Bancário reply, you receive a URL for a form that contains information about the Boleto Bancário. Display the information in this form to your customer exactly as you received it so that the customer can easily transcribe it or print it and give it to their bank. Note You are responsible for storing the Boleto Bancário form URL. You might want to present the URL or its contents to the customer if you have to remind them that their payment is unexpectedly late and that the Boleto Bancário will time out soon. CyberSource does not store the URL. API Fields This section provides detailed information about the Simple Order API fields for the Boleto Bancário payment service. For information about the data types, see Getting Started with CyberSource Advanced for the Simple Order API. Data Type Definitions For more information about these data types, see the World Wide Web Consortium (W3C) XML Schema Part 2: DataTypes specification. Integer Whole number {..., -3, -2, -1, 0, 1, 2, 3,...}. String Sequence of letters, numbers, spaces, and special characters, such and #. Global Payment Service Developer Guide March

85 Chapter 6 Boletos Bancários Using the Simple Order API Request Fields The following table describes the fields to use in a request for the boletopaymentservice service. Table 23 Request Fields for Boletos Bancários for the Simple Order API Request Field Description Required or Optional Data Type & Length billto_firstname Customer s first name. Required String (60) billto_lastname Customer s last name. Required String (60) billto_personalid boletopaymentservice_ expirationdate boletopaymentservice_ instruction boletopaymentservice_run Personal identifier. For CyberSource Latin American Processing, you can use this field for the Cadastro de Pessoas Fisicas (CPF). Expiration date of the Boleto Bancário in GMT in ISO format: YYYY-MM-DD. Text instructions for the Boleto Bancário. This field allows you to specify the text that will be printed in the customer message field on the Boleto form. The customer message field is often used to remind the customer to submit the Boleto promptly. Whether to include boletopaymentservice in your request. Possible values: true: Include the service in your request. false (default): Do not include the service in your request. Optional String (18) Optional String (10) Optional String (512) Required String (50) item_#_unitprice linktorequest Per-item price of the product. You must include either this field or purchasetotals_ grandtotalamount in your request. For more information about items and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API. This value cannot be negative. You can include a decimal point (.) in this field, but you cannot include any other special characters. The amount will be truncated at the request level to the correct number of decimal places. Value that links the current request to a previous authorization request for a debit card or prepaid card. This value is useful when using multiple payment methods to complete an order. For more information about partial authorizations, see Credit Card Services Using the Simple Order API. Optional Decimal (15) Optional String (26) Global Payment Service Developer Guide March

86 Chapter 6 Boletos Bancários Using the Simple Order API Table 23 Request Fields for Boletos Bancários for the Simple Order API (Continued) Request Field Description Required or Optional merchantid merchantreferencecode purchasetotals_ grandtotalamount Your CyberSource merchant ID. Note When opening your account with CyberSource, be sure to inform CyberSource if you plan to use multiple CyberSource merchant IDs. For example, if you have separate business units within your company, each with a separate CyberSource merchant ID, you must have a separate processor merchant ID for each CyberSource merchant ID. For more information, contact Customer Support. Merchant-generated order reference or tracking number. For more information, see Getting Started with CyberSource Advanced for the Simple Order API. Grand total for the order. You must include either this field or item_#_unitprice in your request. For more information, see Getting Started with CyberSource Advanced for the Simple Order API. Required String (30) Required String (50) Required Data Type & Length Decimal (15) Reply Fields The following table describes the fields returned in a reply from boletopaymentservice. Table 24 Reply Fields for Boletos Bancários for the Simple Order API Reply Field Description Data Type & Length boletopaymentreply_ amount boletopaymentreply_ boletonumber boletopaymentreply_ expirationdate boletopaymentreply_ reasoncode boletopaymentreply_ reconciliationid Total amount of the Boleto Bancário payment. Decimal (15) Boleto Bancário payment number. String (6) Expiration date of the Boleto Bancário in GMT. On the face of the Boleto Bancário, the date is in the European format: DD-MM-YYYY. For this expiration date field, the date is mapped to an ISO format: YYYY-MM-DD hh:mm:ss. Note There is a space between the date and the time. Numeric value corresponding to the result of the Boleto Bancário request. See Appendix B, "Reason Codes," on page 155. Unique value generated by CyberSource. For more information about tracking orders, see Getting Started with CyberSource Advanced for the Simple Order API. String (20) Integer (5) String (60) Global Payment Service Developer Guide March

87 Chapter 6 Boletos Bancários Using the Simple Order API Table 24 Reply Fields for Boletos Bancários for the Simple Order API (Continued) Reply Field Description Data Type & Length boletopaymentreply_ requestdatetime Time of the Boleto Bancário request in UTC. Format: YYYY-MM-DDThh:mm:ssZ. Example: T22:47:57Z which is August 11, 2007 at 10:47:57 P.M. The T separates the date and the time. The Z indicates UTC. Date and time (20) boletopaymentreply_url URL of the Boleto Bancário form. String (255) decision invalidfield_0 N merchantreferencecode missingfield_0...n Summarizes the result of the overall request. Possible values: ACCEPT ERROR REJECT For more information about decision values, see Getting Started with CyberSource Advanced for the Simple Order API. Fields in the request that contained invalid data. These reply fields are included as an aid to software developers only. Do not attempt to use these fields for end user interaction. For more information about missing and invalid fields, see Getting Started with CyberSource Advanced for the Simple Order API. Order reference or tracking number that you provided in the request. If you included multi-byte characters in this field in the request, the returned value might contain corrupted characters. For more information about tracking orders, see Getting Started with CyberSource Advanced for the Simple Order API. Required fields that were missing from the request. These reply fields are included as an aid to software developers only. Do not attempt to use these fields for end user interaction. For more information about missing and invalid fields, see Getting Started with CyberSource Advanced for the Simple Order API. String (6) String (100) String (50) String (100) purchasetotals_currency Currency used for the order. The only possible value is BRL. String (5) reasoncode requestid Numeric value corresponding to the result of the overall request. See Appendix B, "Reason Codes," on page 155. Identifier for the request. For more information about request tokens, see Getting Started with CyberSource Advanced for the Simple Order API. Integer (5) String (26) Global Payment Service Developer Guide March

88 Chapter 6 Boletos Bancários Using the Simple Order API Examples Name-Value Pairs: Request Example 27 Boleto Bancário Request billto_firstname=jane billto_lastname=smith billto_personalid=1111 merchantid=okgo merchantreferencecode= item_0_unitprice=10.00 boletopaymentservice_run=true boletopaymentservice_instruction=this is a test boletopaymentservice_expirationdate= Name-Value Pairs: Reply Example 28 Boleto Bancário Reply decision=accept reasoncode=100 requestid= merchantreferencecode= purchasetotals_currency=brl boletopaymentreply_reasoncode=100 boletopaymentreply_reconciliationid= boletopaymentreply_amount=10.00 boletopaymentreply_boletonumber= boletopaymentreply_expirationdate= :59:59 boletopaymentreply_url= reenvia.asp?id_transacao=93b5668a d5-ad d Global Payment Service Developer Guide March

89 Chapter 6 Boletos Bancários Using the Simple Order API XML: Request Example 29 Boleto Bancário Request <requestmessage xmlns="urn:schemas-cybersource-com:transaction-data-1.42"> <billto> <firstname>jane</firstname> <lastname>smith</lastname> <personalid>1111</personalid> </billto> <merchantid>okgo</merchantid> <merchantreferencecode> </merchantreferencecode> <item id="0"><unitprice>10.00</unitprice></item> <boletopaymentservice run="true"> <instruction>this is a test</instruction> <expirationdate> </expirationdate> </boletopaymentservice> </requestmessage> XML: Reply Example 30 Boleto Bancário Reply <c:replymessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.42"> <c:decision>accept</c:decision> <c:reasoncode>100</c:reasoncode> <c:requestid> </c:requestid> <c:merchantreferencecode> </c:merchantreferencecode> <c:purchasetotals><c:currency>brl</c:currency></c:purchasetotals> <c:boletopaymentreply> <c:reasoncode>100</c:reasoncode> <c:reconciliationid> </c:reconciliationid> <c:amount>10.00</c:amount> <c:boletonumber>123456</c:boletonumber> <c:expirationdate> :59:59</c:expirationDate> <c:url> Id_Transacao=93b5668a d5-ad d997479</c:url> </c:boletopaymentreply> </c:replymessage> Global Payment Service Developer Guide March

90 Boletos Bancários Using the SCMP API CHAPTER 7 Requesting a Boleto Bancário Use the ics_boleto_payment field to request the Boleto Bancário payment service. See Table 25, page 90, for a list of the fields. In the Boleto Bancário reply, you receive a URL for a form that contains information about the Boleto Bancário. Display the information in this form to your customer exactly as you received it so that the customer can easily transcribe it or print it and give it to their bank. Note You are responsible for storing the Boleto Bancário form URL. You might want to present the URL or its contents to the customer if you have to remind them that their payment is unexpectedly late and that the Boleto Bancário will time out soon. CyberSource does not store the URL. API Fields This section provides detailed information about the SCMP API fields for the Boleto Bancário payment service. For information about the data types, see Getting Started with CyberSource Advanced for the SCMP API. Request Fields The following table describes the fields to use in a request for the ics_boleto_payment service. Table 25 Request-Level Fields for Boletos Bancários for the SCMP API Request-Level Field boleto_payment_ expiration_date Description Expiration date of the Boleto Bancário in GMT in ISO format: YYYY-MM-DD. Required or Optional Data Type & Length Optional String (10) Global Payment Service Developer Guide March

91 Chapter 7 Boletos Bancários Using the SCMP API Table 25 Request-Level Fields for Boletos Bancários for the SCMP API (Continued) Request-Level Field boleto_payment_ instruction Text instructions for the Boleto Bancário. This field allows you to specify the text that will be printed in the customer message field on the Boleto Bancários form. The customer message field is often used to remind the customer to submit the Boleto Bancários promptly. Optional String (512) customer_firstname Customer s first name. Required String (60) customer_lastname Customer s last name. Required String (60) grand_total_amount ics_applications link_to_request merchant_id merchant_ref_ number Description Grand total for the order. You must include either this field or offer0 and the offer-level field amount. For more information about offers and grand totals, see Getting Started with CyberSource Advanced for the SCMP API. Service to process for the request. For a Boleto Bancário request, this value must be ics_boleto_ payment. Value that links the current request to a previous authorization request for a debit card or prepaid card. This value is useful when using multiple payment methods to complete an order. For more information about partial authorizations, see Credit Card Services Using the SCMP API. Your CyberSource merchant ID. Note When opening your account with CyberSource, make sure that you inform CyberSource if you plan to use multiple CyberSource merchant IDs. For example, when you have separate business units within your company, each with a separate CyberSource merchant ID, you must have a separate processor merchant ID for each CyberSource merchant ID. For more information, contact Customer Support. Merchant-generated order reference or tracking number. For more information about tracking orders, see Getting Started with CyberSource Advanced for the SCMP API. Required or Optional Required Data Type & Length Decimal (15) Required String (255) Optional String (26) Required String (30) Required String (50) Global Payment Service Developer Guide March

92 Chapter 7 Boletos Bancários Using the SCMP API Table 25 Request-Level Fields for Boletos Bancários for the SCMP API (Continued) Request-Level Field offern: amount personal_id Description Per-item price of the product. You must include this field, the offer0 field, or the request-level field grand_total_amount in your request. This value cannot be negative. For more information about offers and grand totals, see Getting Started with CyberSource Advanced for the SCMP API. You can include a decimal point (.) in this field, but you cannot include any other special characters. The amount will be truncated at the request level to the correct number of decimal places. Personal identifier. For CyberSource Latin American Processing, you can use this field for the Cadastro de Pessoas Fisicas (CPF). Required or Optional Optional Data Type & Length Decimal (15) Optional String (18) Reply Fields The following table describes the fields returned in a reply from the ics_boleto_payment service request. Table 26 Reply Fields for Boletos Bancários for the SCMP API Reply Field Description Data Type & Length boleto_payment_amount Total amount of the Boleto Bancário payment. Decimal (15) boleto_payment_boleto_ number Boleto Bancário payment number. String (6) boleto_payment_expiration_ date boleto_payment_rcode boleto_payment_request_ time Expiration date of the Boleto Bancário in GMT. On the face of the Boleto Bancário, the date is in the European format: DD-MM-YYYY. For this expiration date field, the date is mapped to an ISO format: YYYY-MM-DD hh:mm:ss. Note There is a space between the date and the time. One-digit code that indicates whether the ics_boleto_payment request was successful: -1: An error occurred 0: The request was declined 1: The request was successful For more information about handling replies, see Getting Started with CyberSource Advanced for the SCMP API. Time of the Boleto Bancário request in UTC. For more information about the format, see the data type information in Getting Started with CyberSource Advanced for the SCMP API. String (20) Integer (1) Date and time (20) Global Payment Service Developer Guide March

93 Chapter 7 Boletos Bancários Using the SCMP API Table 26 Reply Fields for Boletos Bancários for the SCMP API (Continued) Reply Field Description Data Type & Length boleto_payment_rflag boleto_payment_rmsg boleto_payment_trans_ref_ no One-word description of the result of the ics_boleto_payment request. See "Reply Flags," page 94, and for more information, see Getting Started with CyberSource Advanced for the SCMP API. Message that explains the reply flag boleto_payment_rflag. Do not display this message to the customer and do not use this field to write an error handler. For more information, see Getting Started with CyberSource Advanced for the SCMP API. Unique value generated by CyberSource. For more information, see Getting Started with CyberSource Advanced for the SCMP API. String (50) String (255) String (60) boleto_payment_url URL of the Boleto Bancário form. String (255) currency Currency used for the order. The only possible value is BRL. String (5) ics_rcode One-digit code that indicates whether the entire request was successful: -1: An error occurred 0: The request was declined 1: The request was successful For more information, see Getting Started with CyberSource Advanced for the SCMP API. Integer (1) ics_rflag ics_rmsg merchant_ref_number request_id One-word description of the result of the entire request. See "Reply Flags," page 94, and for more information, see Getting Started with CyberSource Advanced for the SCMP API. Message that explains the reply flag ics_rflag. Do not display this message to the customer, and do not use this field to write an error handler. For more information, see Getting Started with CyberSource Advanced for the SCMP API. Order reference or tracking number that you provided in the request. If you included multi-byte characters in this field in the request, the returned value might contain corrupted characters. For more information about tracking orders, see Getting Started with CyberSource Advanced for the SCMP API. Unique identifier generated by CyberSource for the transaction. For more information about request IDs, see Getting Started with CyberSource Advanced for the SCMP API. String (50) String (255) String (50) String (26) Global Payment Service Developer Guide March

94 Chapter 7 Boletos Bancários Using the SCMP API Reply Flags The following table describes the reply flags for the ics_boleto_payment service request. Table 27 Reply Flags for Boletos Bancários for the SCMP API Reply Flag DBOLETODECLINED DINVALIDDATA DMISSINGFIELD ESYSTEM ETIMEOUT SOK Description When CyberSource sent a Boleto Bancário request to CyberSource Latin American Processing, the processor returned an error to CyberSource. Data provided is not consistent with the request. The request is missing a required field. System error. You must design your transaction management system to correctly handle CyberSource system errors. Depending on the payment processor handling the transaction, the error may indicate a valid CyberSource system error or a processor rejection caused by invalid data. In either case, CyberSource recommends that you do not design your system to endlessly retry sending a transaction. For important information on handling system errors and retries, see the SDK for your CyberSource client. The request timed out. The transaction was successful. Global Payment Service Developer Guide March

95 Chapter 7 Boletos Bancários Using the SCMP API Request and Reply Examples Request Example 31 Boleto Bancário Request bill_city=louisville bill_country=bra currency=brl customer_firstname=joe customer_lastname=doe ics_applications=ics_boleto_payment merchant_id=philpot2 merchant_ref_number= offer0=product_code:electronic_software^merchant_product_ sku:testdl^quantity:1^amount:1.18^tax_amount:0.00^product_name:clorox Wipes^offer_id:0 boleto_payment_instruction=my test boleto_payment_expiration_date= personal_id=1111 Reply Example 32 Boleto Bancário Reply boleto_payment_url= Transacao=93b5668a d5-ad d ics_rcode=1 ics_rmsg=request was processed successfully. request_id= boleto_payment_rcode=1 boleto_payment_boleto_number= boleto_payment_rmsg=request was processed successfully. boleto_payment_trans_ref_no= ics_rflag=sok boleto_payment_rflag=sok merchant_ref_number= boleto_payment_expiration_date= :59:59 Global Payment Service Developer Guide March

96 Reports for Boletos Bancários CHAPTER 8 Boleto Bancário Unfulfilled Report The Boleto Bancário Unfulfilled Report provides information about Boleto Bancário transactions that have been issued but not fulfilled. The reasons for an unfulfilled Boleto Bancário are: The customer has not submitted the Boleto Bancário. The Boleto Bancário is still in the Brazilian clearing system. A transaction continues to be included in the Boleto Bancário Unfulfilled Report every day until: CyberSource Latin American Processing confirms that the transaction has been funded. The Boleto Bancário expires. To view the Boleto Bancário Unfulfilled Report, you must subscribe to it on the Business Center. Viewing and Downloading Reports There are two ways to view and download Boleto Bancário Unfulfilled reports: Through an API See the first chapter in the Reporting Developer Guide, which is available at the Support Center, for information about requesting a report with a client application. On the CyberSource Business Center For information about downloading the Boleto Bancário Unfulfilled Report from the Business Center, see the Business Center help topic Downloading Detail Reports. Global Payment Service Developer Guide March

97 Chapter 8 Reports for Boletos Bancários To view and download reports: Step 1 Step 2 Step 3 Navigate to the Boleto Bancário Unfulfilled Report. Click I need help with this page. A help topic for the Boleto Bancário Unfulfilled Report opens. In the help topic, click Downloading Reports. The Downloading Detail Reports topic opens. The Boleto Bancário Unfulfilled Report is a detail report, and you can download it the same way that you download other reports. For additional information, see the first chapter in the Reporting Developer Guide, which is available at the Support Center. XML Conventions and Data Types Syntax for Report Declarations A report declaration has this syntax: <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Report SYSTEM URIreference> <Report Name=CDATA Version=NMTOKEN xmlns=cdata MerchantID=CDATA ReportDate=CDATA> The value of the URIreference tag is the same as the value of the xmlns tag. Whether you are operating in test or live mode, the namespace always refers to ebctest instead of ebc. Global Payment Service Developer Guide March

98 Chapter 8 Reports for Boletos Bancários Syntax for Element Declarations An element declaration has this syntax: <Sample Attribute=CDATA> (Element) (ChoiceOne) (ChoiceTwo) (ComplexElement) (RequiredRecurringElement)+ (OptionalElement)? (OptionalRecurringElement)* </Sample> The DTDs for the reports can use syntax with the?, +, or * character inside the parentheses. Table 28 Conventions for Element Declarations Convention <Sample> Attribute=CDATA (Element) (ChoiceOne) (ChoiceTwo) (ComplexElement) (RequiredRecurringElement)+ (OptionalElement)? (OptionalRecurringElement)* Description Parent of the subsequent elements. Name of the attribute followed by the XML data format for the attribute. Required element. Must appear only once. Element <ChoiceOne> or <ChoiceTwo> but not both. Element with one or more children. Required element. Can appear one or more times. Optional element. Can appear once or be omitted. Optional element. Can appear zero or more times. Data Types and Lengths In each description, the data length indicates the maximum length for that data type. Table 29 Data Types for XML Reports Data Type Description Alphanumeric String containing letters, numbers, and special characters such #, and %. All text uses UTF-8 character encoding. Boolean Amount Date Single character: T for true or F for false. Can include a decimal point. YYYY-MM-DD where: YYYY is the four-digit year MM is the two-digit month DD is the two-digit day The hyphens are included in a Date value. Global Payment Service Developer Guide March

99 Chapter 8 Reports for Boletos Bancários Table 29 Data Type DateTime Data Types for XML Reports (Continued) Description YYYY-MM-DDTHH:MM:SS[+ -]HH:MM where: YYYY is the four-digit year MM is the two-digit month DD is the two-digit day T separates the date information from the time information HH is the two-digit hours MM is the two-digit minutes SS is the two-digit seconds [+ -]HH:MM is the time zone s offset from GMT (Greenwich Mean Time) The hyphens are included in a DateTime value. Numeric String containing numbers. Elements in the Report <Report> The <Report> element is the root of the report. Syntax <?xml version="1.0" encoding="utf-8"?> <Report Name=CDATA Version=CDATA xmlns=cdata MerchantID=CDATA ReportDate=CDATA> (Summary) (TransactionDetail)? </Report> Global Payment Service Developer Guide March

100 Chapter 8 Reports for Boletos Bancários Attributes Table 30 Attributes of <Report> in the Boleto Bancário Unfulfilled Report Attribute Name Description Data Type & Length Name Name of the report. This value is always Boleto Bancário Unfulfilled Report. Alphanumeric (100) Version Version number of the report. Numeric (10) xmlns XML namespace for the report. This value is always ebc/reports/dtd/bbur.dtd. Alphanumeric (100) MerchantID CyberSource merchant ID. Alphanumeric (30) ReportDate Date the report was generated. DateTime (25) Child Elements Table 31 Child Elements of <Report> in the Boleto Bancário Unfulfilled Report Element Name <Summary> <TransactionDetail> Description Summary of the transaction information for each range. See "<Summary>," page 101. Information about all of the unfunded transactions that have occurred during the previous 3 to 180 days. See "<TransactionDetail>," page 104. Example Example 33 <Report> Element <?xml version="1.0" encoding="utf-8"?> <Report Name="BoletoBancarioUnfulfilledReport" Version="1.0" xmlns= MerchantID="exampleMerchant" ReportDate=" T08:00:00-08:00"> <Summary>... </Summary> <TransactionDetail>... </TransactionDetail> </Report> Global Payment Service Developer Guide March

101 Chapter 8 Reports for Boletos Bancários <Summary> The <Summary> element contains a summary of the transaction information for each range: 3 days outstanding 4 days outstanding 5 to 7 days outstanding 8 to 14 days outstanding 15 to 30 days outstanding 31 to 60 days outstanding 61 to 90 days outstanding 91 to 180 days outstanding 3 to 180 days outstanding Syntax <Summary> (Range)* </Summary> Child Element Table 32 Child Element of <Summary> in the Boleto Bancário Unfulfilled Report Element Name <Range> Description Summary of the transaction information for one range. See "<Range>," page 103. Example Example 34 <Summary> Element <Summary> <Range DaysOutstandingStart="3" DaysOutstandingEnd="3" CurrencyCode="BRL"> <Count>0</Count> <NetAmount>0.00</NetAmount> </Range> <Range DaysOutstandingStart="3" DaysOutstandingEnd="3" CurrencyCode="USD"> <Count>0</Count> <NetAmount>0.00</NetAmount> </Range> <Range DaysOutstandingStart="4" DaysOutstandingEnd="4" CurrencyCode="BRL"> <Count>0</Count> <NetAmount>0.00</NetAmount> </Range> <Range DaysOutstandingStart="4" DaysOutstandingEnd="4" CurrencyCode="USD"> <Count>0</Count> <NetAmount>0.00</NetAmount> </Range> Global Payment Service Developer Guide March

102 Chapter 8 Reports for Boletos Bancários Example 34 <Summary> Element (Continued) <Range DaysOutstandingStart="5" DaysOutstandingEnd=" 7" CurrencyCode="BRL"> <Count>2</Count> <NetAmount>121.38</NetAmount> </Range> <Range DaysOutstandingStart="5" DaysOutstandingEnd=" 7" CurrencyCode="USD"> <Count>0</Count> <NetAmount>0.00</NetAmount> </Range> <Range DaysOutstandingStart="8" DaysOutstandingEnd="14" CurrencyCode="BRL"> <Count>8</Count> <NetAmount>823.40</NetAmount> </Range> <Range DaysOutstandingStart="8" DaysOutstandingEnd="14" CurrencyCode="USD"> <Count>0</Count> <NetAmount>0.00</NetAmount> </Range> <Range DaysOutstandingStart="15" DaysOutstandingEnd="30" CurrencyCode="BRL"> <Count>21</Count> <NetAmount> </NetAmount> </Range> <Range DaysOutstandingStart="15" DaysOutstandingEnd="30" CurrencyCode="USD"> <Count>0</Count> <NetAmount>0.00</NetAmount> </Range> <Range DaysOutstandingStart="31" DaysOutstandingEnd="60" CurrencyCode="BRL"> <Count>7</Count> <NetAmount>777.17</NetAmount> </Range> <Range DaysOutstandingStart="31" DaysOutstandingEnd="60" CurrencyCode="USD"> <Count>0</Count> <NetAmount>0.00</NetAmount> </Range> <Range DaysOutstandingStart="61" DaysOutstandingEnd="90" CurrencyCode="BRL"> <Count>0</Count> <NetAmount>0.00</NetAmount> </Range> <Range DaysOutstandingStart="61" DaysOutstandingEnd="90" CurrencyCode="USD"> <Count>0</Count> <NetAmount>0.00</NetAmount> </Range> <Range DaysOutstandingStart="91 DaysOutstandingEnd="180" CurrencyCode="BRL"> <Count>0</Count> <NetAmount>0.00</NetAmount> </Range> <Range DaysOutstandingStart="91 DaysOutstandingEnd="180" CurrencyCode="USD"> <Count>0</Count> <NetAmount>0.00</NetAmount> </Range> Global Payment Service Developer Guide March

103 Chapter 8 Reports for Boletos Bancários Example 34 <Summary> Element (Continued) <Range DaysOutstandingStart="3" DaysOutstandingEnd="180" CurrencyCode="BRL"> <Count>38</Count> <NetAmount> </NetAmount> </Range> <Range DaysOutstandingStart="3" DaysOutstandingEnd="180" CurrencyCode="USD"> <Count>0</Count> <NetAmount>0.00</NetAmount> </Range> </Summary> <Range> The <Range> element contains a summary of the transaction information for one currency in one range. Syntax <Range DaysOutstandingStart=CDATA DaysOutstandingEnd=CDATA CurrencyCode=CDATA> (Count) (NetAmount) </Range> Table 33 Attributes of <Range> in the Boleto Bancário Unfulfilled Report Attribute Name Description Data Type & Length DaysOutstandingStart DaysOutstandingEnd CurrencyCode Start of the range of the number of days outstanding. For example, for the range of 5 to 7 days outstanding, the start of the range is 5. End of the range of the number of days outstanding. For example, for the range of 5 to 7 days outstanding, the end of the range is 7. Currency code. Possible value: BRL Alphanumeric (4) Alphanumeric (4) Alphanumeric (5) Global Payment Service Developer Guide March

104 Chapter 8 Reports for Boletos Bancários Child Elements Table 34 Child Elements of <Range> in the Boleto Bancário Unfulfilled Report Element Name Count NetAmount Description Number of transactions that await funding in the currency specified by CurrencyCode and in the range specified by DaysOutstandingStart and DaysOutstandingEnd. Sum of transactions that await funding in the currency specified by CurrencyCode and in the range specified by DaysOutstandingStart and DaysOutstandingEnd. Example Example 35 <Range> Element <Range DaysOutstandingStart="3" DaysOutstandingEnd="3" CurrencyCode="CNY"> <Count>2</Count> <NetAmount>121.38</NetAmount> </Range> <TransactionDetail> The <TransactionDetail> element contains information about all of the unfunded transactions that have occurred during the previous 3 to 180 days. Syntax <TransactionDetail> (Transaction)* </TransactionDetail> Child Elements Table 35 Child Element of <TransactionDetail> in the Boleto Bancário Unfulfilled Report Element Name <Transaction> Description Information about an unfunded transaction. See "<Transaction>," page 105. Global Payment Service Developer Guide March

105 Chapter 8 Reports for Boletos Bancários Example Example 36 <TransactionDetail> Element <TransactionDetail> <Transaction>... </Transaction> </TransactionDetail> <Transaction> The <Transaction> element contains information about an unfunded transaction. Syntax <Transaction Processor=CDATA DaysOutstanding=CDATA MerchantID=CDATA OriginalTransactionDate=CDATA RequestID=CDATA TransactionReferenceNumber=CDATA MerchantReferenceNumber=CDATA Amount=CDATA CurrencyCode=CDATA EventType=CDATA BoletoNumber=CDATA </Transaction> Table 36 Attributes of <Transaction> in the Boleto Bancário Unfulfilled Report Attribute Name Description Data Type & Length Processor DaysOutstanding Payment processor used for the transaction. This value is always brazilboleto: braspag. Number of days since the transaction was initiated. Alphanumeric (40) Alphanumeric (4) MerchantID CyberSource merchant ID. Alphanumeric (30) OriginalTransactionDate RequestID Date that the original payment transaction was initiated. Unique identifier generated by CyberSource for the transaction. For more information about request IDs, see Getting Started with CyberSource Advanced for the Simple Order API or Getting Started with CyberSource Advanced for the SCMP API. DateTime (25) Numeric (26) Global Payment Service Developer Guide March

106 Chapter 8 Reports for Boletos Bancários Table 36 Attributes of <Transaction> in the Boleto Bancário Unfulfilled Report (Continued) Attribute Name Description Data Type & Length TransactionReference Number MerchantReference Number Amount CurrencyCode CyberSource-generated reference or tracking number for the transaction. You can use this value to reconcile your CyberSource reports with your processor reports. This value corresponds to: <service>_reconciliationid for the Simple Order API. <service>_trans_ref_no for the SCMP API. For more information about tracking orders, see Getting Started with CyberSource Advanced for the Simple Order API or Getting Started with CyberSource Advanced for the SCMP API. Merchant-generated reference or tracking number for the transaction. You can use this value to perform searches in the CyberSource Business Center. This value corresponds to: merchantreferencecode for the Simple Order API. merchant_ref_number for the SCMP API. See the information about tracking orders, see Getting Started with CyberSource Advanced for the Simple Order API or Getting Started with CyberSource Advanced for the SCMP API. Amount of the transaction. For refunds, the amount is negative. Currency code used for the transaction. Possible value: BRL Alphanumeric (60) Alphanumeric (50) Amount (19) Alphanumeric (5) Global Payment Service Developer Guide March

107 Chapter 8 Reports for Boletos Bancários Table 36 Attributes of <Transaction> in the Boleto Bancário Unfulfilled Report (Continued) Attribute Name Description Data Type & Length EventType BoletoNumber Type of event that occurred for the transaction. Possible values: Expired: The Boleto Bancário has expired and will not be accepted for payment by Brazilian financial institutions. Fulfilled: The bank issuing the Boleto Bancário has received funds and deposited them into your account. Pending Fulfillment: The Boleto Bancário was issued, but the customer has not submitted it yet, or it is still in the Brazilian clearing system. The number identifying the Boleto Bancário payment involved in the transaction. Alphanumeric (20) Alphanumeric (15) Example Example 37 <Transaction> Element <Transaction Processor="brazilboleto" DaysOutstanding="3" MerchantID=" " OriginalTransactionDate=" T10:45:00-08:00" RequestID=" " TransactionReferenceNumber="123456" MerchantReferenceNumber=" " Amount="75,00" CurrencyCode="BRL" EventType="Fulfilled" BoletoNumber="987654"> </Transaction> Global Payment Service Developer Guide March

108 Chapter 8 Reports for Boletos Bancários DTD <!ELEMENT Report (Summary, TransactionDetail)> <!ATTLIST Report Name CDATA #REQUIRED Version NMTOKEN #REQUIRED xmlns CDATA #REQUIRED MerchantID CDATA #REQUIRED ReportDate CDATA #REQUIRED> <!ELEMENT Summary (Range*)> <!ELEMENT Range (Count, NetAmount)> <!ATTLIST Range DaysOutStandingStart CDATA #REQUIRED DaysOutStandingEnd CDATA #REQUIRED CurrencyCode CDATA #REQUIRED> <!ELEMENT Count (#PCDATA)> <!ELEMENT NetAmount (#PCDATA)> <!ELEMENT TransactionDetail (Transaction*)> <!ELEMENT Transaction EMPTY> <!ATTLIST Transaction Processor CDATA #REQUIRED DaysOutstanding CDATA #REQUIRED MerchantID CDATA #REQUIRED OriginalTransactionDate CDATA #REQUIRED RequestID CDATA #REQUIRED TransactionReferenceNumber CDATA #REQUIRED MerchantReferenceNumber CDATA #REQUIRED Amount CDATA #REQUIRED CurrencyCode CDATA #REQUIRED EventType CDATA #REQUIRED BoletoNumber CDATA #REQUIRED> Global Payment Service Developer Guide March

109 Chapter 8 Reports for Boletos Bancários Example This report example consists of the following unfulfilled transactions: One payment totalling 1.20 BRL, 3 days outstanding Five payments totalling 6.00 BRL, 5-7 days outstanding Six payments totalling 7.20 BRL, days outstanding These transactions are included in the following ranges in the <Summary> section: 3 days outstanding 5 to 7 days outstanding 3 to 14 days outstanding Example 38 Unfulfilled Transactions <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Report SYSTEM " dtd/bbur.dtd"> <Report Name="BoletoBancarioUnfulfilledReport" Version="1.0" xmlns=" MerchantID="examplemerchant" ReportDate=" T08:00:00-08:00"> <Summary> <Range DaysOutstandingStart="3" DaysOutstandingEnd="3" CurrencyCode="BRL"> <Count>1</Count> <NetAmount>1.20</NetAmount> </Range> <Range DaysOutstandingStart="4" DaysOutstandingEnd="4" CurrencyCode="BRL"> <Count>0</Count> <NetAmount>0.00</NetAmount> </Range> <Range DaysOutstandingStart="5" DaysOutstandingEnd="7" CurrencyCode="BRL"> <Count>5</Count> <NetAmount>6.00</NetAmount> </Range> <Range DaysOutstandingStart="8" DaysOutstandingEnd="14" CurrencyCode="BRL"> <Count>6</Count> <NetAmount>7.20</NetAmount> Global Payment Service Developer Guide March

110 Chapter 8 Reports for Boletos Bancários </Range> </Summary> <TransactionDetail> <Transaction Processor="brazilboleto" DaysOutstanding="3" MerchantID="examplemerchant" OriginalTransactionDate=" T00:14:40-08:00" RequestID=" " TransactionReferenceNumber=" _1684_ " MerchantReferenceNumber=" " Amount="1.20" CurrencyCode="BRL" EventType="Pending Fulfillment" BoletoNumber=" "/> <Transaction Processor="brazilboleto" DaysOutstanding="5" MerchantID="examplemerchant" OriginalTransactionDate=" T02:38:24-08:00" RequestID=" " TransactionReferenceNumber=" _1684_ " MerchantReferenceNumber=" " Amount="1.20" CurrencyCode="BRL" EventType="Pending Fulfillment" BoletoNumber=" "/> <Transaction Processor="brazilboleto" DaysOutstanding="5" MerchantID="examplemerchant" OriginalTransactionDate=" T02:38:24-08:00" RequestID=" " TransactionReferenceNumber=" _1684_ " MerchantReferenceNumber=" " Amount="1.20" CurrencyCode="BRL" EventType="Pending Fulfillment" BoletoNumber=" "/> <Transaction Processor="brazilboleto" DaysOutstanding="6" MerchantID="examplemerchant" OriginalTransactionDate=" T02:38:24-08:00" RequestID=" " TransactionReferenceNumber=" _1684_ " MerchantReferenceNumber=" " Amount="1.20" CurrencyCode="BRL" EventType="Pending Fulfillment" BoletoNumber=" "/> <Transaction Processor="brazilboleto" DaysOutstanding="7" MerchantID="examplemerchant" OriginalTransactionDate=" T02:38:24-08:00" RequestID=" " TransactionReferenceNumber=" _1684_ " Global Payment Service Developer Guide March

111 Chapter 8 Reports for Boletos Bancários MerchantReferenceNumber=" " Amount="1.20" CurrencyCode="BRL" EventType="Pending Fulfillment" BoletoNumber=" "/> <Transaction Processor="brazilboleto" DaysOutstanding="7" MerchantID="examplemerchant" OriginalTransactionDate=" T02:38:24-08:00" RequestID=" " TransactionReferenceNumber=" _1684_ " MerchantReferenceNumber=" " Amount="1.20" CurrencyCode="BRL" EventType="Pending Fulfillment" BoletoNumber=" "/> </TransactionDetail> </Report> Global Payment Service Developer Guide March

112 Chapter 8 Reports for Boletos Bancários Single Transaction Report Version 1.4 of the Single Transaction Report is supported for Boletos Bancários. It is described in the Reporting Developer Guide. The On-Demand Single Transaction Report provides you with the status of the transaction while the transaction is occurring. Example 39 Query for a Single Transaction <form action=" method="post"> <table> <tr> <td>merchantid</td> <td><input type="text" name="merchantid" value="nwtest1"></td> </tr> <tr> <td>type</td> <td><input type="text" name="type" value="transaction"></td> </tr> <tr> <td>subtype</td> <td><input type="text" name="subtype" value="transactiondetail"></td> </tr> <tr> <td>requestid</td> <td><input type="text" name="requestid" value=" "></td> </tr> <tr> <td>versionnumber</td> <td><input type="text" name="versionnumber" value="1.4"></td> </tr> <tr> <td></td> <td><input type="reset"> <input type="submit" value="submit"></input></td> </tr> </table> </form> Global Payment Service Developer Guide March

113 Chapter 8 Reports for Boletos Bancários Example 40 Single Transaction Report <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE Report (View Source for full doctype...)> <Report xmlns=" Name="Transaction Detail" Version="1.4" MerchantID="nwtest1" ReportStartDate=" T19:50:59-08:00" ReportEndDate=" T19:50:59-08:00"> <Requests> <Request MerchantReferenceNumber=" " RequestDate=" T14:00:08-08:00" RequestID=" " SubscriptionID="" Source="SCMP API" TransactionReferenceNumber=" " PredecessorRequestID= > <BillTo> <FirstName>Jane</FirstName> <LastName>Smith</LastName> <Address1>1295 Charleston Road</Address1> <Address2>Suite 2</Address2> <City>Mountain View</City> <State>CA</State> <Zip>94043</Zip> < /> <Country>US</Country> </BillTo> <ShipTo> <LastName>Smith</LastName> <Address1>1295 Charleston Road</Address1> <Address2>Suite 2</Address2> <City>Mountain View</City> <State>CA</State> <Zip>94043</Zip> <Country>US</Country> </ShipTo> <PaymentMethod> <Card> <AccountSuffix /> <ExpirationMonth /> <ExpirationYear /> <CardType>Brazil Bank Transfer</CardType> <BoletoNumber>12345</BoletoNumber> </Card> </PaymentMethod> Global Payment Service Developer Guide March

114 Chapter 8 Reports for Boletos Bancários Example 40 Single Transaction Report (Continued) <LineItems> <LineItem Number="0"> <FulfillmentType /> <Quantity>1</Quantity> <UnitPrice>1.56</UnitPrice> <TaxAmount>0.25</TaxAmount> <MerchantProductSKU>testdl</MerchantProductSKU> <ProductName>PName1</ProductName> <ProductCode>electronic_software</ProductCode> </LineItem> </LineItems> <ApplicationReplies> <ApplicationReply Name="ics_boleto_payment"> <RCode>1</RCode> <RFlag>SOK</RFlag> <RMsg>Request was processed successfully.</rmsg> </ApplicationReply> </ApplicationReplies> <PaymentData> <PaymentProcessor>payeasecn</PaymentProcessor> <Amount>1.81</Amount> <CurrencyCode>BRL</CurrencyCode> <TotalTaxAmount>0.25</TotalTaxAmount> <EventType>Fulfilled</EventType> <NumberOfInstallments>5</NumberOfInstallments> </PaymentData> </Request> </Requests> </Report> Global Payment Service Developer Guide March

115 Direct Debits and Direct Debit Refunds Using the Simple Order API CHAPTER 9 Important Our processing partner requires us to pre-populate their fields to show that the mandate has been signed and dated. The MANDATEDATE field is populated with the system date, the MANDATEPLACE field is populated with the customer city, and the MANDATESIGNED indicator is set to 1. These fields are for future use and will support e-mandates. Requesting Direct Debits Important From August 1, 2016, for euro countries and from October 31, 2016, for noneuro countries, the IBAN must be included in each request. If you provide a BBAN it will be converted to an IBAN; this conversion process will continue only until August 1, Note The bank SWIFT code, a unique address of the bank, does not have to be included in each request; however, CyberSource strongly recommends including this code in the request when the IBAN is included in the request. To request a direct debit, set the directdebitservice_run field to true. See Table 37, page 118, for the fields to use when requesting the service. For an example Direct Debit request, see page 128. When requesting a direct debit, you may not request any of the other ICS services except Tax Calculation. For more information about the service, see Tax Calculation Service Using the Simple Order API. When you take an order that uses a direct debit, you must gather the customer s billing and bank account information. For most countries, CyberSource accepts either the traditional bank account information or the account s IBAN. The traditional bank account information and the corresponding API fields you need to provide vary by country. Contact CyberSource Customer Support for required country-specific bank account information. Global Payment Service Developer Guide March

116 Chapter 9 Direct Debits and Direct Debit Refunds Using the Simple Order API CyberSource validates the format of the bank account number before processing the direct debit. If the account number does not pass the validation check, CyberSource rejects the request with a reasoncode=244. CyberSource recommends that you then confirm the customer entered the number correctly, and if it was incorrect, request the refund again with the correct number. Requesting Direct Debit Refunds Important From August 1, 2016, for euro countries and from October 31, 2016, for noneuro countries, the IBAN must be included in each request. If you provide a BBAN it will be converted to an IBAN; this conversion process will continue only until August 1, There are two types of direct debit refunds: follow-on refunds and stand-alone refunds. A follow-on refund uses information from a previous direct debit. A stand-alone refund does not depend on a previous transaction. A follow-on refund must occur within 60 of the request for the direct debit. When the time limit for a follow-on refund expires, the only kind of refund you can perform is a standalone refund. To request a direct debit refund: Set the directdebitrefundservice_run field to true. Do not request any other ICS services except Tax Calculation, which is optional. For more information about this service, see Tax Calculation Service Using the Simple Order API. Send the fields required for a direct debit refund request as described in Table 37, page 118. For a follow-on refund, the fields and values must match the fields and values you sent in the original direct debit request. For a stand-alone refund, the directdebitrefundservice_directdebitrequestid field is optional. See page 129. For a follow-on refund, include the directdebitrefundservice_ directdebitrequestid field with the request ID from the direct debit reply is required. See page 130. The easiest way to implement direct debit refunds is to always send the request ID from the original direct debit with every direct debit refund request. CyberSource recommends that when you request a refund, you use the same value for merchantreferencecode that you used for the direct debit. This makes it easier Global Payment Service Developer Guide March

117 Chapter 9 Direct Debits and Direct Debit Refunds Using the Simple Order API for you to link the refund to the original direct debit in your own system as well as in CyberSource reports and Transaction Search Screens. CyberSource performs basic checks on the format of the bank account number before processing the direct debit refund. If the account number does not pass the validation check, CyberSource rejects the request with a reasoncode=244. CyberSource recommends that you then confirm the customer entered the number correctly, and if it was incorrect, request the refund again with the correct number. You may perform multiple partial refunds against a direct debit. The sum of the refunds may not exceed the amount of the payment. You will not receive an error in the reply for any of the following conditions: The directdebitrefundservice_requestid field is invalid. The customer s payment has not yet been received. Instead, CyberSource will not process the refund and the transaction will appear in the daily Transaction Exception Detail Report. You should monitor this report daily to determine if any of your transactions have problems. For descriptions of the reason codes that can appear in the report, see "Reason Codes," page 155. For more information about the report, see the Global Payment Service Planning Guide. For details about downloading the report and its format, see the Reporting Developer Guide. Global Payment Service Developer Guide March

118 Chapter 9 Direct Debits and Direct Debit Refunds Using the Simple Order API API Fields For information about the data types, see Getting Started with CyberSource Advanced for the Simple Order API. Request Fields The following table lists the fields to use in a request for the directdebitservice service or the directdebitrefundservice service. Table 37 Request Fields for Direct Debits and Direct Debit Refunds for the Simple Order API Request Field Description Required (R) or Optional (O) bankinfo_address Bank s address. Direct Debit (O) bankinfo_bankcode bankinfo_branchcode bankinfo_city bankinfo_country bankinfo_name Bank's code. Used for some countries when you are not using the IBAN. Contact CyberSource Customer Support for required country-specific bank account information. Code that identifies the branch of the customer's bank when you are not using the IBAN. Contact CyberSource Customer Support for required country-specific bank account information. City in which the bank is located. If you do not send this field, Global Collect assumes that the billto_city field contains the bank name. Some banks validate the bank account information, so consider sending this field if the bank is not located in billto_ city. Country in which the bank is located. Possible values are the two-character ISO Standard Country Codes. Bank's name. Required when using the Global Collect processor to make one of the following types of direct debit transactions: Direct debit Refund (O) Direct Debit (See Refund (See Direct Debit (See Refund (See Direct Debit (See Refund (See Direct Debit (R) Refund (R) Direct Debit (See Refund (See Data Type & Length String (255) String (See String (15) String (35) String (2) String (40) Stand-alone direct debit refund Otherwise it is optional. Global Payment Service Developer Guide March

119 Chapter 9 Direct Debits and Direct Debit Refunds Using the Simple Order API Table 37 Request Fields for Direct Debits and Direct Debit Refunds for the Simple Order API (Continued) Request Field Description Required (R) or Optional (O) bankinfo_swiftcode Bank s SWIFT code. Unique address of the bank. Also known as the Bank Identification Code (BIC). Note This field is optional; however, CyberSource strongly recommends including this code in each request when the IBAN is included in the request. Direct Debit (O) Refund (O) billto_city City for the billing address. Direct Debit (R) billto_country billto_ Country for the billing address. Possible values are the two-character ISO Standard Country Codes. Customer s address, including the full domain name. For example, [email protected]. Refund (R) Direct Debit (R) Refund (R) Direct Debit (R) Refund (R) billto_firstname Customer s first name. Direct Debit (R) Refund (R) billto_lastname Customer s last name. Direct Debit (R) Refund (R) billto_phonenumber Customer s telephone number. Direct Debit (O) billto_postalcode billto_state Postal code for the billing address. The postal code must consist of 5 to 9 digits. If the value of billto_country is US, the 9- digit postal code must follow this format: [5 digits][dash][4 digits] Example: If the value of billto_country is CA, the 6- digit postal code must follow this format: [alpha][numeric][alpha] [numeric][alpha][numeric] Example: A1B 2C3 State for the billing address. Required if billto_country is US or CA. Otherwise optional. Possible values are the State, Province, and Territory Codes for the United States and Canada. Refund (O) Direct Debit (R if billto_country is US or CA) Refund (R if billto_country is US or CA) Direct Debit (See Refund (See billto_street1 Street address for the billing address. Direct Debit (R) Refund (R) Data Type & Length String (30) String (50) String (2) String (255) String (60) String (60) String (15) String (10) String (2) String (60) Global Payment Service Developer Guide March

120 Chapter 9 Direct Debits and Direct Debit Refunds Using the Simple Order API Table 37 Request Fields for Direct Debits and Direct Debit Refunds for the Simple Order API (Continued) Request Field Description Required (R) or Optional (O) Data Type & Length billto_street2 directdebitrefundservice_ directdebitrequestid directdebitrefundservice_ reconciliationid directdebitrefundservice_run directdebitservice_ datecollect directdebitservice_ directdebittext directdebitservice_ directdebittype directdebitservice_mandate AuthenticationDate Additional street address information for the billing address. The requestid value returned from a previous request for directdebitservice. To use this field, contact CyberSource Customer Support. Flag indicating whether or not to include the directdebitrefundservice service in your request. Possible values: true: Include the service in your request false (default): Do not include the service in your request Date on which the direct debit should be debited. This field is only for the Global Collect processor. Format: YYYYMMDD Text describing the reason for the direct debit. This field is required only for the Global Collect processor. Appears on the customer s bank statement. Austria: Max 28 characters Germany: Max 50 characters Netherlands: Max 32 characters Spain: Max 40 characters Type of direct debit. This field is required only for the Global Collect processor. The possible values are: 001: Austria 003: Netherlands 004: Spain 005: German ELV direct debit The date the direct debit mandate was authenticated. Format: YYYYMMDD Direct Debit (O) Refund (O) Refund (R for follow-on refunds. Not used for standalone refunds.) String (60) String (26) Refund (R) String (60) Refund (R) String (5) Direct Debit (O) Numeric (8) Direct Debit (See Direct Debit (See String (See String (3) Direct Debit (O) Numeric (8) Global Payment Service Developer Guide March

121 Chapter 9 Direct Debits and Direct Debit Refunds Using the Simple Order API Table 37 Request Fields for Direct Debits and Direct Debit Refunds for the Simple Order API (Continued) Request Field Description Required (R) or Optional (O) Data Type & Length directdebitservice_ recurringtype directdebitservice_run directdebitservice_ transactiontype Whether the direct debit is the first or last direct debit associated with the mandate, or one in between. This field is only for the United Kingdom. The possible values are: 001: First direct debit associated with this mandate. Use this value for a onetime direct debit. 002: Subsequent direct debits associated with this mandate. 003: Last direct debit associated with this mandate. Flag indicating whether or not to include the directdebitservice service in your request. Possible values: true: Include the service in your request false (default): Do not include the service in your request Type of direct debit transaction. This field is required only for the Netherlands when using the Global Collect processor. The possible values are: 01: First collection using this account 02: Other Note For first collections on a Post giro account called onzuivere posten, the account number is verified against the account name and city by the Post bank. This verification requires one additional processing day. Direct Debit (See String (3) Direct Debit (R) String (5) Direct Debit (See String (2) fundtransfer_accountname Name used on the bank account. Direct Debit (R) Refund (R) String (30) Global Payment Service Developer Guide March

122 Chapter 9 Direct Debits and Direct Debit Refunds Using the Simple Order API Table 37 Request Fields for Direct Debits and Direct Debit Refunds for the Simple Order API (Continued) Request Field Description Required (R) or Optional (O) Data Type & Length fundtransfer_accountnumber Bank account number. Note From August 1, 2016, for euro countries and from October 31, 2016, for non-euro countries, the IBAN must be included in each request. If you provide a BBAN it will be converted to an IBAN, and this conversion process will continue only until August 1, Direct Debit (See Refund (See String (See Note Do not use the IBAN in this field. include the IBAN in the fundtransfer_ iban field. fundtransfer_bankcheckdigit Code used to validate the customer's account number when you are not using the IBAN. Contact CyberSource Customer Support for required country-specific bank account information. Direct Debit (See String (2) fundtransfer_iban International Bank Account Number (IBAN) for the bank account. Direct Debit (See Alphanumeric (50) Note From August 1, 2016, for euro countries and from October 31, 2016, for non-euro countries, the IBAN must be included in each request. If you provide a BBAN it will be converted to an IBAN, and this conversion process will continue only until August 1, item_#_productcode Type of product. This value is also used to determine the category that the product falls under: electronic, handling, physical, service, or shipping. The default value is default. See "Product Codes," page 154, for a list of valid values. Direct Debit (O) Refund (O) String (30) For direct debits, if you set this field to a value other than default, stored_ value, or any of the values related to shipping or handling, the item_#_quantity, item_#_productname field and the item_ #_productsku fields are required. item_#_productname Product s name. For direct debits, required if item_#_productcode is not default, stored_value, or one of the values related to shipping and/or handling. Direct Debit (See Refund (O) String (30) Global Payment Service Developer Guide March

123 Chapter 9 Direct Debits and Direct Debit Refunds Using the Simple Order API Table 37 Request Fields for Direct Debits and Direct Debit Refunds for the Simple Order API (Continued) Request Field Description Required (R) or Optional (O) Data Type & Length item_#_productsku Product identifier code. For direct debits, required if item_#_productcode is not default, stored_value, or one of the values related to shipping or handling. Direct Debit (See Refund (O) String (30) item_#_quantity Quantity of the product being purchased. The default is 1. For direct debits, required if item_#_productcode is not default, stored_value, or one of the values related to shipping or handling. Direct Debit (See Refund (O) Integer (10) item_#_taxamount Tax amount associated with this item. The field is additive. For example, if you send one item with unitprice of and taxamount of 0.80, and you send another item with unitprice of and taxamount of 1.60, the total amount authorized will be for 32.40, not with 2.40 of tax included. Direct Debit (O) Refund (O) String (15) The item_#_taxamount and the item_#_ unitprice fields must use the same currency. If you include item_#_taxamount field, and you also include taxservice service in your request, the taxservice service does not calculate tax for the item. Instead, it returns the value in the item_#_ taxamount field. item_#_unitprice Per-item price of the product. You must include either this field or purchasetotals_grandtotalamount in your request. This value cannot be negative. For more information about items and grand totals, see Getting Started with CyberSource Advanced for the Simple Order API. Direct Debit (See Refund (See String (15) You can include a decimal point (.) in this field, but you cannot include any other special characters. The amount will be truncated at the request level to the correct number of decimal places. Global Payment Service Developer Guide March

124 Chapter 9 Direct Debits and Direct Debit Refunds Using the Simple Order API Table 37 Request Fields for Direct Debits and Direct Debit Refunds for the Simple Order API (Continued) Request Field Description Required (R) or Optional (O) Data Type & Length linktorequest merchantid merchantreferencecode purchasetotals_currency purchasetotals_ grandtotalamount Value that links the current request to a previous authorization request for a debit card or prepaid card. This value is useful when multiple payment methods are being used to complete an order. For more information, see Credit Card Services Using the Simple Order API. Your CyberSource merchant ID. Note When opening your account with CyberSource, make sure that you inform CyberSource whether you plan to use multiple CyberSource merchant IDs. For example, if you have separate business units within your company, each with a separate CyberSource merchant ID. You must have a separate processor merchant ID for each CyberSource merchant ID. For more information, contact CyberSource Customer Support. Merchant-generated order reference or tracking number. For more information, see Getting Started with CyberSource Advanced for the Simple Order API. Currency used for the order. Possible values are the ISO Standard Currency Codes. Grand total for the order. You must include either this field or the item_#_unitprice field in your request. For more information, see, Getting Started with CyberSource Advanced for the Simple Order API. Direct Debit (O) String (26) Direct Debit (R) Refund (R) Direct Debit (R) Refund (R) Direct Debit (R) Refund (R) Direct Debit (See Refund (See shipto_city City of the shipping address. Direct Debit (Required if any shipping information is included) shipto_country shipto_firstname shipto_lastname Country of the shipping address. Possible values are the two-character ISO Standard Country Codes. First name of the person receiving the product. Last name of the person receiving the product. String (30) String (50) String (5) String (15) String (50) Direct Debit (O) String (2) Direct Debit (O) String (60) Direct Debit (O) String (60) Global Payment Service Developer Guide March

125 Chapter 9 Direct Debits and Direct Debit Refunds Using the Simple Order API Table 37 Request Fields for Direct Debits and Direct Debit Refunds for the Simple Order API (Continued) Request Field Description Required (R) or Optional (O) Data Type & Length shipto_phonenumber Phone number for the shipping address. Direct Debit (O) String (15) shipto_postalcode shipto_state Postal code for the shipping address. The postal code must consist of 5 to 9 digits. If the value of shipto_country is US, the 9-digit postal code must follow these rules: [5 digits][dash][4 digits] Example: If the value of shipto_country is CA, the 6-digit postal code must follow these rules: [alpha][numeric][alpha] [numeric][alpha][numeric] Example: A1B 2C4 If the postal code for the shipping address is not included in the request message, CyberSource uses the postal code from the billing address. If the postal code for the billing address is not included in the request message, the postal code for the shipping address is required. State or province of the shipping address. Required if shipto_country=us or CA.Possible values are the State, Province, and Territory Codes for the United States and Canada. Direct Debit (R if shipto_ country=us or CA) Direct Debit (See shipto_street1 First line of the shipping address. Direct Debit (Required if any shipping information is included) String (10) String (2) String (60) shipto_street2 Second line of the shipping address. Direct Debit (O) String (60) Global Payment Service Developer Guide March

126 Chapter 9 Direct Debits and Direct Debit Refunds Using the Simple Order API Reply Fields The following table lists the fields returned in a reply from the directdebitservice service or the directdebitrefundservice service. Table 38 Direct Debit and Direct Debit Refund Reply Fields for the Simple Order API Reply Field Description Returned By Data Type & Length decision Summary of the result for the overall request. Possible values: Direct Debit and Refund String (6) ACCEPT ERROR REJECT directdebitrefundreply_ amount Total amount for the direct debit refund. Refund String (15) directdebitrefundreply_iban directdebitrefundreply_ processorresponse directdebitrefundreply_ reasoncode directdebitrefundreply_ reconciliationid directdebitrefundreply_ requestdatetime International Bank Account Number (IBAN) for the bank account. Refund Alphanumeric (50) Response code from the processor. Refund String (10) Numeric value that indicates the result of the direct debit refund request. See "Reason Codes," page 155, for a list of possible values. Unique value generated by CyberSource. For more information, see Getting Started with CyberSource Advanced for the Simple Order API. Time of the direct debit refund request in UTC. Format: YYYY-MM-DDThh:mm:ssZ. Example: T22:47:57Z, which is August 11, 2007, at 10:47:57 P.M. The T separates the date and the time. The Z indicates UTC. Refund Integer (5) Refund String (60) Refund String (20) directdebitreply_amount Total amount for the direct debit. Direct Debit String (15) directdebitreply_iban directdebitreply_mandateid directdebitreply_ processorresponse directdebitreply_reasoncode International Bank Account Number (IBAN) for the bank account. The identification reference for the direct debit mandate. Direct Debit Direct Debit Alphanumeric (50) Alphanumeric (16) Response code from the processor. Direct Debit String (10) Numeric value that indicates the result of the direct debit request. See "Reason Codes," page 155, for a list of possible values. Direct Debit Integer (5) Global Payment Service Developer Guide March

127 Chapter 9 Direct Debits and Direct Debit Refunds Using the Simple Order API Table 38 Direct Debit and Direct Debit Refund Reply Fields for the Simple Order API (Continued) Reply Field Description Returned By Data Type & Length directdebitreply_ reconciliationid directdebitreply_ requestdatetime invalidfield_0...n merchantreferencecode missingfield_0...n purchasetotals_currency reasoncode Unique value generated by CyberSource. For more information, see Getting Started with CyberSource Advanced for the Simple Order API. Time of the direct debit request in UTC. Format: YYYY-MM-DDThh:mm:ssZ. Example: T22:47:57Z, which is August 11, 2007 at 10:47:57 P.M. The T separates the date and the time. The Z indicates UTC. Fields in the request that contained invalid data. These reply fields are included as an aid to software developers only. No attempt should be made to use these fields for end user interaction. For more information, see Getting Started with CyberSource Advanced for the Simple Order API. Order reference or tracking number that you provided in the request. If you included multi-byte characters in this field in the request, the returned value might contain corrupted characters. Required fields that were missing from the request. These reply fields are included as an aid to software developers only. No attempt should be made to use these fields for end user interaction. For more information, see Getting Started with CyberSource Advanced for the Simple Order API. Currency used for the order. Possible values are the ISO Standard Currency Codes. Numeric value that indicates the result of the overall request. See "Reason Codes," page 155, for a list of possible values. Direct Debit String (60) Direct Debit String (20) Direct Debit and Refund Direct Debit and Refund Direct Debit and Refund Direct Debit and Refund Direct Debit and Refund requestid Identifier for the request. Direct Debit and Refund String (100) String (50) String (100) String (5) Integer (5) String (26) Global Payment Service Developer Guide March

128 Chapter 9 Direct Debits and Direct Debit Refunds Using the Simple Order API Request and Reply Examples Note In the direct debit example below the customer includes the BBAN in the request. The BBAN is converted to an IBAN in the direct debit reply. Direct Debit Request Example 41 Direct Debit Request <requestmessage xmlns="urn:schemas-cybersource-com:transaction-data-1.103"> <merchantid>demo123</merchantid> <merchantreferencecode>demoref</merchantreferencecode> <billto> <firstname>orlando</firstname> <lastname>bloom</lastname> <street1>kaerntner Strasse 22</street1> <city>vienna</city> <postalcode>1010</postalcode> <country>es</country> <phonenumber> </phonenumber> < >[email protected]</ > </billto> <purchasetotals> <currency>eur</currency> <grandtotalamount>41</grandtotalamount> </purchasetotals> <fundtransfer> <accountnumber> </accountnumber> <bankcheckdigit>90</bankcheckdigit> </fundtransfer> <bankinfo> <bankcode>0081</bankcode> <name>sloveniabank_testing</name> <country>es</country> <branchcode>5394</branchcode> <swiftcode>abna NL 2A</swiftCode> </bankinfo> <directdebitservice run="true"> <directdebittext>abcd</directdebittext> <directdebittype>004</directdebittype> <mandateauthenticationdate> </mandateauthenticationdate> </directdebitservice> </requestmessage> Global Payment Service Developer Guide March

129 Chapter 9 Direct Debits and Direct Debit Refunds Using the Simple Order API Direct Debit Reply Example 42 Direct Debit Reply <c:replymessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.103"> <c:merchantreferencecode>demoref</c:merchantreferencecode> <c:requestid> </c:requestid> <c:decision>accept</c:decision> <c:reasoncode>100</c:reasoncode> <c:purchasetotals> <c:currency>eur</c:currency> </c:purchasetotals> <c:directdebitreply> <c:reasoncode>100</c:reasoncode> <c:amount>41.00</c:amount> <c:requestdatetime> t23:52:01z</c:requestdatetime> <c:reconciliationid> </c:reconciliationid> <c:mandateid> </c:mandateid> <c:iban>ie64bofi </c:iban> </c:directdebitreply> </c:replymessage> Standalone Direct Debit Refund Request Note In the direct debit refund example below the customer includes the BBAN in the request. The BBAN is converted to an IBAN in the direct debit refund reply. Example 43 Standalone Direct Debit Refund Request <requestmessage xmlns="urn:schemas-cybersource-com:transaction-data-1.103"> <merchantid>demo123</merchantid> <merchantreferencecode>demoref</merchantreferencecode> <billto> <firstname>orlando</firstname> <lastname>bloom</lastname> <street1>33, rue Dauphine</street1> <city>bergheim</city> <postalcode>75006</postalcode> <country>de</country> <phonenumber> </phoneNumber> < >[email protected]</ > </billto> <purchasetotals> <currency>eur</currency> <grandtotalamount>12</grandtotalamount> </purchasetotals> Global Payment Service Developer Guide March

130 Chapter 9 Direct Debits and Direct Debit Refunds Using the Simple Order API <fundtransfer> <accountnumber> </accountnumber> <accountname>bradford NICKLES</accountName> </fundtransfer> <bankinfo> <bankcode> </bankcode> <name>sloveniabank_testing</name> <country>de</country> <swiftcode>bsljsi2x</swiftcode> </bankinfo> <directdebitservice run=""> <reconciliationid> </reconciliationid> </directdebitservice> <directdebitrefundservice run="true"/> </requestmessage> Example 44 Standalone Direct Debit Refund Reply <c:replymessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.103"> <c:merchantreferencecode>demoref</c:merchantreferencecode> <c:requestid> </c:requestid> <c:decision>accept</c:decision> <c:reasoncode>100</c:reasoncode> <c:purchasetotals> <c:currency>eur</c:currency> </c:purchasetotals> <c:directdebitrefundreply> <c:reasoncode>100</c:reasoncode> <c:amount>12.00</c:amount> <c:requestdatetime> t23:53:50z</c:requestdatetime> <c:reconciliationid> </c:reconciliationid> <c:processorresponse>800</c:processorresponse> <c:iban>de </c:iban> </c:directdebitrefundreply> </c:replymessage> Example 45 Follow-On Direct Debit Refund Follow-On Direct Debit Refund Request <requestmessage xmlns="urn:schemas-cybersource-com:transaction-data-1.103"> <merchantid>demo123</merchantid> <merchantreferencecode>demoref</merchantreferencecode> <purchasetotals> <grandtotalamount>41</grandtotalamount> </purchasetotals> <directdebitrefundservice run="true"> <directdebitrequestid> </directdebitrequestid> </directdebitrefundservice> </requestmessage> Global Payment Service Developer Guide March

131 Chapter 9 Direct Debits and Direct Debit Refunds Using the Simple Order API Example 46 Follow-On Direct Debit Refund Reply <c:replymessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.103"> <c:merchantreferencecode>demoref</c:merchantreferencecode> <c:requestid> </c:requestid> <c:decision>accept</c:decision> <c:reasoncode>100</c:reasoncode> <c:purchasetotals> <c:currency>eur</c:currency> </c:purchasetotals> <c:directdebitrefundreply> <c:reasoncode>100</c:reasoncode> <c:amount>41.00</c:amount> <c:requestdatetime> t23:52:39z</c:requestdatetime> <c:reconciliationid> </c:reconciliationid> <c:iban>ie64bofi </c:iban> </c:directdebitrefundreply> </c:replymessage> Global Payment Service Developer Guide March

132 Direct Debits and Direct Debit Refunds Using the SCMP API CHAPTER 10 Important Our processing partner requires us to pre-populate their fields to show that the mandate has been signed and dated. The MANDATEDATE field is populated with the system date, the MANDATEPLACE field is populated with the customer city, and the MANDATESIGNED indicator is set to 1. These fields are for future use and will support e-mandates. Requesting Direct Debits Important From August 1, 2016, for euro countries and from October 31, 2016, for noneuro countries, the IBAN must be included in each request. If you provide a BBAN it will be converted to an IBAN; this conversion process will continue only until August 1, Note The bank SWIFT code, a unique address of the bank, does not have to be included in each request; however, CyberSource strongly recommends including this code in the request when the IBAN is included in the request. To request a direct debit, set the ics_applications field to ics_direct_debit. See Table 39, page 135, for a list of the fields to use. When requesting a direct debit, you may not request any of the other ICS services except ics_tax. For more information about the service, see Tax Calculation Service Using the SCMP API. When you take an order that uses a direct debit, you must gather the customer s billing and bank account information. For most countries, CyberSource accepts either the traditional bank account information or the account s IBAN. The traditional bank account information and the corresponding API fields you need to provide vary by country. Contact CyberSource Customer Support for required country-specific bank account information. CyberSource validates the format of the bank account number before performing the direct debit. If the account number does not pass the validation check, CyberSource Global Payment Service Developer Guide March

133 Chapter 10 Direct Debits and Direct Debit Refunds Using the SCMP API rejects the request with a rflag=dinvalidaccount. CyberSource recommends that you confirm the customer entered the number correctly, and if it was incorrect, request the direct debit again with the correct number. Requesting Direct Debit Refunds Important From August 1, 2016, for euro countries and from October 31, 2016, for noneuro countries, the IBAN must be included in each request. If you provide a BBAN it will be converted to an IBAN; this conversion process will continue only until August 1, There are two types of direct debit refunds: follow-on refunds and stand-alone refunds. A follow-on refund uses information from a previous direct debit. A stand-alone refund does not depend on a previous transaction. A follow-on refund must occur within 60 of the request for the direct debit. When the time limit for a follow-on refund expires, the only kind of refund you can perform is a standalone refund. To request a direct debit refund: Set the ics_applications field to ics_direct_debit_refund. Do not request any other ICS services except Tax Calculation, which is optional. For more information about this service, see Tax Calculation Service Using the SCMP API. Send the fields required for a direct debit refund request as described in Table 39, page 135. For a follow-on refund, the fields and values must match the fields and values you sent in the original direct debit request. For a stand-alone refund, the direct_debit_request_id field is optional. See page 147. For a follow-on refund, include the direct_debit_request_id field with the request ID from the direct debit reply. See page 148. The easiest way to implement direct debit refunds is to always send the request ID from the original direct debit with every direct debit refund request. CyberSource recommends that when you request a refund, you use the same value for the merchant_ref_number field that you used for the direct debit. This makes it easier for you to link the refund to the original direct debit in your own system as well as in CyberSource reports and Transaction Search Screens. Global Payment Service Developer Guide March

134 Chapter 10 Direct Debits and Direct Debit Refunds Using the SCMP API CyberSource validates the format of the bank account number before processing the direct debit refund. If the account number does not pass the validation check, CyberSource rejects the request with a rflag=dinvalidaccount. CyberSource recommends that you then confirm the customer entered the number correctly, and if it was incorrect, request the refund again with the correct number. You can perform multiple partial refunds against a direct debit. The sum of the refunds must not exceed the amount of the payment. You will not receive an error in the reply for either of the following conditions: The direct_debit_request_id field is invalid. The customer s payment has not yet been received. Instead, CyberSource does not process the refund, and the transaction appears in the daily Transaction Exception Detail Report. You should monitor this report daily to determine whether any of your transactions have problems. For descriptions of the reason codes that can appear in the report, see Appendix B, "Reason Codes," on page 155. For information about the report and how to use it, see the Global Payment Service Planning Guide. For details about downloading the report and its format, see the Reporting Developer Guide. Global Payment Service Developer Guide March

135 Chapter 10 Direct Debits and Direct Debit Refunds Using the SCMP API API Fields In the Used By column, the services are referred to by shortened names: Direct Debit and Refund. For information about the data types, see Getting Started with CyberSource Advanced for the SCMP API. Request Fields The following table lists the fields to use in a request for the ics_direct_debit service or the ics_direct_debit_refund service. Table 39 Request-Level Fields for Direct Debits and Direct Debit Refunds for the SCMP API Request-Level Field bank_account_ name bank_account_ number Description Name used on the bank account. Bank account number. Important From August 1, 2016, for euro countries and from October 31, 2016, for non-euro countries, the IBAN must be included in each request. If you provide a BBAN it will be converted to an IBAN, and this conversion process will continue only until August 1, Note Do not use the IBAN in this field. include the IBAN in the fundtransfer_iban field. Required (R) or Optional (O) Direct Debit (O) Refund (O) Direct Debit (See Refund (See bank_address Bank s address. Direct Debit (O) bank_check_digit bank_city bank_code Code used to validate the customer's account number when you are not using the IBAN. Contact CyberSource Customer Support for required country-specific bank account information. City in which the bank is located. If you do not send this field, Global Collect assumes the bank is located in the bill_city field. Some banks validate the bank account information, so include this field if the bank is not included in the bill_city field. Bank's code. Used for some countries when you are not using the IBAN. Contact CyberSource Customer Support for required country-specific bank account information. Refund (O) Direct Debit (See Direct Debit (O) Refund (O) Direct Debit (See Refund (See Data Type & Length String (30) String (See String (255) String (2) String (35) String (See Global Payment Service Developer Guide March

136 Chapter 10 Direct Debits and Direct Debit Refunds Using the SCMP API Table 39 Request-Level Fields for Direct Debits and Direct Debit Refunds for the SCMP API (Continued) Request-Level Field Description Required (R) or Optional (O) Data Type & Length bank_country Country in which the bank is located. Possible values are the two-character ISO Standard Country Codes. Direct Debit (R) Refund (R) String (2) bank_iban International Bank Account Number (IBAN) for the bank account. Important From August 1, 2016, for euro countries and from October 31, 2016, for non-euro countries, the IBAN must be included in each request. If you provide a BBAN it will be converted to an IBAN, and this conversion process will continue only until August 1, Direct Debit (See Alphanumeric (50) bank_name Bank's name. Required when using the Global Collect processor to make one of the following types of direct debit transactions: Direct Debit (See String (40) Direct debit Stand-alone direct debit refund Refund (See Otherwise optional. bank_swiftcode Bank s SWIFT code. Unique address of the bank. Also known as the Bank Identification Code (BIC). Note This field is optional; however, CyberSource strongly recommends including this code in each request when the IBAN is included in the request. Direct Debit (O) Refund (O) bill_address1 Billing street address. Direct Debit (R) Refund (R) bill_address2 Additional billing address information. Direct Debit (O) Refund (O) bill_city Billing address city. Direct Debit (R) bill_country bill_state Billing address country. Possible values are the twocharacter ISO Standard Country Codes. Billing address state. Required if bill_country=us or CA. Possible values are the State, Province, and Territory Codes for the United States and Canada. Refund (R) Direct Debit (R) Refund (R) Direct Debit (See Description) Refund (See Description) String (30) String (60) String (60) String (50) String (2) String (2) Global Payment Service Developer Guide March

137 Chapter 10 Direct Debits and Direct Debit Refunds Using the SCMP API Table 39 Request-Level Fields for Direct Debits and Direct Debit Refunds for the SCMP API (Continued) Request-Level Field bill_zip branch_code currency customer_ customer_ firstname customer_ lastname Zip code for the shipping address. The zip code must consist of 5 to 9 digits. If the value of bill_country is US, the 9-digit zip code must follow this format: [5 digits][dash][4 digits] Example: If the value of bill_country is CA, the 6-digit zip code must follow this format: [alpha][numeric][alpha] [numeric][alpha][numeric] Example: A1B 2C3 Code that identifies the branch of the customer's bank when you are not using the IBAN. Contact CyberSource Customer Support for required country-specific bank account information. Currency used for the order. Possible values are the ISO Standard Currency Codes. Customer s address, including the full domain name. For example, [email protected]. Customer s first name. Customer s last name. Direct Debit (R if bill_ country=us or CA) Refund (R if bill_ country=us or CA) Direct Debit (See Refund (See Direct Debit (R) Refund (R) Direct Debit (R) Refund (R) Direct Debit (R) Refund (R) Direct Debit (R) Refund (R) customer_phone Customer s telephone number. Direct Debit (O) date_collect direct_debit_ mandate_ authentication_ date Description Date the direct debit should be debited. Format: YYYYMMDD The date the direct debit mandate was authenticated. Format: YYYYMMDD Required (R) or Optional (O) Refund (O) Data Type & Length String (10) String (15) String (5) String (255) String (60) String (60) String (15) Direct Debit (O) String (8) Direct Debit (O) Numeric (8) Global Payment Service Developer Guide March

138 Chapter 10 Direct Debits and Direct Debit Refunds Using the SCMP API Table 39 Request-Level Fields for Direct Debits and Direct Debit Refunds for the SCMP API (Continued) Request-Level Field Description Required (R) or Optional (O) Data Type & Length direct_debit_ recurring_type Whether the direct debit is the first or last direct debit associated with the mandate, or one in between. Required only for the United Kingdom. Possible values: Direct Debit (See String (3) 001: First direct debit associated with this mandate. Use this value if a one-time direct debit). 002: Subsequent direct debits associated with this mandate. 003: Last direct debit associated with this mandate. direct_debit_ request_id direct_debit_text direct_debit_ trans_ref_no direct_debit_type The request_id value returned from a previous request for ics_direct_debit. Text describing reason for the direct debit. Required only for the Global Collect processor. Appears on the customer s bank statement. Austria: Max 28 characters Germany: Max 50 characters Netherlands: Max 32 characters Spain: Max 40 characters To use this field, contact CyberSource Customer Support. Type of direct debit. Required only for the Global Collect processor. Possible values: 001: Austria 003: Netherlands 004: Spain 005: German ELV direct debit Refund (R) String (26) Direct Debit (R) String (See Refund (R) String (60) Direct Debit (See String (3) grand_total_ amount Grand total for the order. You must include either this field or the offer0 field and the offer-level field amount. For more information about offers and grand totals, see Getting Started with CyberSource Advanced for the SCMP API. Direct Debit (See Refund (See ics_applications ICS services to process for the request. Direct Debit (R) link_to_request Value that links the current request to a previous authorization request for a debit card or prepaid card. This value is useful when using multiple payment methods to complete an order. For more information, see Credit Card Services Using the SCMP API. Refund (R) Decimal (15) String (255) Direct Debit (O) String (26) Global Payment Service Developer Guide March

139 Chapter 10 Direct Debits and Direct Debit Refunds Using the SCMP API Table 39 Request-Level Fields for Direct Debits and Direct Debit Refunds for the SCMP API (Continued) Request-Level Field mandate_id The mandate ID. Required only for the United Kingdom. Direct Debit (See merchant_id merchant_ref_ number offer0...n ship_to_address1 Your CyberSource merchant ID. Note When opening your account with CyberSource, tell CyberSource whether you plan to use multiple CyberSource merchant IDs. For example, if you have separate business units within your company, each with a separate CyberSource merchant ID. You must have a separate processor merchant ID for each CyberSource merchant ID. For more information, contact CyberSource Customer Support. Merchant-generated order reference or tracking number. For more information, see Getting Started with CyberSource Advanced for the SCMP API. Offers for the request. An offer is a line item for the order. First line of the shipping address. Required if any shipping information is included. Direct Debit (R) Refund (R) Direct Debit (R) Refund (R) Direct Debit (O) Refund (O) Direct Debit (See String (16) String (30) String (50) String (50) String (60) ship_to_address2 Second line of the shipping address. Direct Debit (O) String (60) ship_to_city ship_to_country City of the shipping address. Required if any shipping information is included. Country of the shipping address. Possible values are the two-character ISO Standard Country Codes. Direct Debit (See String (50) Direct Debit (O) String (2) ship_to_firstname First name of person receiving the product. Direct Debit (O) String (60) ship_to_lastname Last name of person receiving the product. Direct Debit (O) String (60) ship_to_phone Phone number for the shipping address. Direct Debit (O) String (15) ship_to_state Description State or province of the shipping address. Required if ship_to_country=us or CA. Possible values are the State, Province, and Territory Codes for the United States and Canada. Required (R) or Optional (O) Direct Debit (See Data Type & Length String (2) Global Payment Service Developer Guide March

140 Chapter 10 Direct Debits and Direct Debit Refunds Using the SCMP API Table 39 Request-Level Fields for Direct Debits and Direct Debit Refunds for the SCMP API (Continued) Request-Level Field Description Required (R) or Optional (O) Data Type & Length ship_to_zip Zip code for the shipping address. If the value of ship_to_country is US, the 9-digit zip code must follow this format: [5 digits][dash][4 digits] Example: Direct Debit (R if ship_to_ country=us or CA) String (10) If the value of ship_to_country is CA, the 6-digit zip code must follow this format: [alpha][numeric][alpha] [numeric][alpha][numeric] Example: A1B 2C3 If the postal code for the shipping address is not included in the request message, CyberSource uses the postal code from the billing address. If the postal code for the billing address is not included in the request message, the postal code for the shipping address is required. timeout Number of seconds until the transaction times out. The default is 110 seconds. Direct Debit (O) Refund (O) Positive integer (3) transaction_type Type of direct debit transaction. Required only for the Netherlands when using the Global Collect processor. Possible values: Direct Debit (See String (2) 01: First collection using this account 02: Other Note For first collections on a Post giro account called onzuivere posten, the account number is verified against the account name and city by the Post bank. This verification requires one additional processing day. Global Payment Service Developer Guide March

141 Chapter 10 Direct Debits and Direct Debit Refunds Using the SCMP API Offer-Level Fields The following table lists the fields to use in a request for the ics_direct_debit service or the ics_direct_debit_refund service. Table 40 Offer-Level Fields for Direct Debits and Direct Debit Refunds for the SCMP API Offer-Level Field Description Required (R) or Optional (O) amount merchant_product_sku product_code product_name quantity Per-item price of the product. You must include either this field and the offer0 field, or the request-level field grand_total_amount in your request. This value cannot be negative. For more information about offers and grand totals, see Getting Started with CyberSource Advanced for the SCMP API. You can include a decimal point (.) in this field, but you cannot include any other special characters. The amount will be truncated at the request level to the correct number of decimal places. Product identifier code. For direct debits, required if product_code is not default, stored_value, or one of the values related to shipping or handling. Type of product. This value is also used to determine the product category: electronic, handling, physical, service, or shipping.the default value is default. See "Product Codes," page 154, for a list of valid values. For direct debits, if you set this to a value other than default, stored_value, or any of the values related to shipping or handling, the quantity, product_name, and merchant_ product_sku fields are required. Product s name. For direct debits, required if product_code is not default, stored_ value, or one of the values related to shipping or handling. Quantity of the product being purchased.the default is 1. For direct debits, required if product_code is not default, stored_ value, or one of the values related to shipping or handling. Direct Debit (See Refund (See Direct Debit (See Refund (O) Direct Debit (O) Refund (O) Direct Debit (See Refund (O) Direct Debit (See Refund (O) Data Type & Length Decimal (15) String (30) String (30) String (30) Nonnegative integer (10) Global Payment Service Developer Guide March

142 Chapter 10 Direct Debits and Direct Debit Refunds Using the SCMP API Table 40 Offer-Level Fields for Direct Debits and Direct Debit Refunds for the SCMP API (Continued) Offer-Level Field Description Required (R) or Optional (O) Data Type & Length tax_amount Tax amount associated with this item.the field is additive. For example, if you send the following offer lines: Direct Debit (O) Refund (O) Decimal (15) offer0=amount:10.00^ quantity:1^tax_amount:0.80 offer1=amount:20.00^ quantity:1^tax_amount:1.60 the total amount authorized will be for 32.40, not with 2.40 of tax included. The tax_amount and amount values must be in the same currency. If you include tax_amount, and you request the ics_tax service, ics_tax will not calculate tax for the offer. Instead, it will return the value in the tax_amount field. Reply Fields The following table lists the fields returned in a reply from ics_direct_debit service request or the ics_direct_debit_refund service request. Table 41 Reply Fields for Direct Debits and Direct Debit Refunds for the SCMP API Reply Field Description Returned By Data Type & Length client_lib_version Information about the client library used to request the transaction. Direct Debit Refund String (50) currency Currency used for the order. Possible values are the ISO Standard Currency Codes. Direct Debit Refund String (5) direct_debit_amount Amount of the direct debit. Direct Debit Decimal (15) direct_debit_iban International Bank Account Number (IBAN) for the bank account. Direct Debit Alphanumeric (50) direct_debit_mandate_id The identification reference for the direct debit mandate. Direct Debit Alphanumeric (16) direct_debit_rcode One-digit code that indicates if the ics_direct_ debit request was successful. Direct Debit Integer (1) direct_debit_refund_ amount Amount of the direct debit refund. Refund Decimal (15) Global Payment Service Developer Guide March

143 Chapter 10 Direct Debits and Direct Debit Refunds Using the SCMP API Table 41 Reply Fields for Direct Debits and Direct Debit Refunds for the SCMP API (Continued) Reply Field Description Returned By direct_debit_refund_ iban direct_debit_refund_ rcode direct_debit_refund_ request_time direct_debit_refund_ response_code direct_debit_refund_ rflag direct_debit_refund_ rmsg direct_debit_refund_ trans_ref_no direct_debit_request_ time direct_debit_response_ code direct_debit_rflag direct_debit_rmsg direct_debit_trans_ref_ no ics_rcode ics_rflag International Bank Account Number (IBAN) for the bank account. One-digit code that indicates if the ics_direct_ debit_refund request was successful. Time of direct debit refund request in UTC. For more information, see Getting Started with CyberSource Advanced for the SCMP API. Refund Alphanumeric (50) Refund Integer (1) Refund Date and time (20) Response code from the processor. Refund String (10) One-word description of the result of the ics_ direct_debit_refund request. Message that explains the reply flag direct_debit_ refund_rflag. Reference number for the transaction. For more information, see Getting Started with CyberSource Advanced for the SCMP API. Time of direct debit request in UTC. For more information, see Getting Started with CyberSource Advanced for the SCMP API. Refund String (50) Refund String (255) Refund String (60) Refund Date and time (20) Response code from the processor. Direct Debit String (10) One-word description of the result for the ics_ direct_debit request. Message that explains the reply flag direct_debit_ rflag. Reference number for the transaction. For more information, see Getting Started with CyberSource Advanced for the SCMP API. One-digit code that indicates whether the entire request was successful. One-word description of the result for the entire request. Direct Debit String (50) Direct Debit String (255) Refund String (60) Direct Debit and Refund Direct Debit and Refund ics_rmsg Message that explains the reply flag ics_rflag. Direct Debit and Refund merchant_ref_number Order reference or tracking number that you provided in the request. If you included multi-byte characters in this field in the request, the returned value might contain corrupted characters. Direct Debit and Refund request_id Identifier for the request generated by the client. Direct Debit and Refund Data Type & Length Integer (1) String (50) String (255) String (50) String (26) Global Payment Service Developer Guide March

144 Chapter 10 Direct Debits and Direct Debit Refunds Using the SCMP API Reply Flags The following table lists the reply flags for the ics_direct_debit service request and the ics_direct_debit_refund service request. Table 42 Reply Flags for Direct Debits and Direct Debit Refunds for the SCMP API Reply Flag Description Returned By DINVALIDACCOUNT The bank account number did not pass the validation. Verify with the customer that the account number is correct; if it was incorrect, request the service again with the correct information. Direct Debit and Refund DINVALIDDATA Data provided is not consistent with the request. Direct Debit and Refund DMISSINGFIELD The request is missing a required field. Direct Debit and Refund ESYSTEM System error. Wait a few minutes before re-sending your request. You must design your transaction management system to correctly handle CyberSource system errors. Depending on the payment processor handling the transaction, the error may indicate a valid CyberSource system error or a processor rejection caused by invalid data. In either case, CyberSource recommends that you do not design your system to endlessly retry sending a transaction. See the documentation for your CyberSource client for information on handling system errors and retries. Direct Debit and Refund ETIMEOUT The request timed out. Direct Debit and Refund SOK The transaction was successful. Direct Debit and Refund Global Payment Service Developer Guide March

145 Chapter 10 Direct Debits and Direct Debit Refunds Using the SCMP API Request and Reply Examples Note In the direct debit example below the customer includes the BBAN in the request. The BBAN is converted to an IBAN in the direct debit reply. Direct Debit Request Example 47 Direct Debit Request ics_applications=ics_direct_debit bank_account_name=direct_debit Testing bank_account_number= bank_address=vienna Central Branch bank_city=hinterbruhl bank_code=31000 bank_country=at bank_swiftcode=abna NL 2A bill_address1=parkstrasse 4 bill_city=hinterbruhl bill_country=at bill_zip=2371 currency=eur customer_ [email protected] customer_firstname=john customer_lastname=smith customer_phone= direct_debit_mandate_authentication_date= direct_debit_text=direct Debit Text direct_debit_type=001 grand_total_amount=21.11 merchant_id=mercid123 merchant_ref_number=merref123 Global Payment Service Developer Guide March

146 Chapter 10 Direct Debits and Direct Debit Refunds Using the SCMP API Example 48 Direct Debit Reply currency=eur direct_debit_amount=21.11 direct_debit_iban=ie64bofi direct_debit_mandate_id= direct_debit_rcode=1 direct_debit_rflag=sok direct_debit_rmsg=request was processed successfully. direct_debit_time= t211943z direct_debit_trans_ref_no= ics_decision_reason_code=100 ics_rcode=1 ics_rflag=sok ics_rmsg=request was processed successfully. merchant_ref_number=merref123 request_id= Global Payment Service Developer Guide March

147 Chapter 10 Direct Debits and Direct Debit Refunds Using the SCMP API Direct Debit Refund Standalone Note In the direct debit refund example below the customer includes the BBAN in the request. The BBAN is converted to an IBAN in the direct debit refund reply. Example 49 Standalone Direct Debit Refund Request ics_applications=ics_direct_debit_refund bank_account_name=direct_debit Testing bank_account_number= bank_address=vienna Central Branch bank_check_digit=77 bank_code=31000 bank_country=at bank_name=raiffeisen Zentral bank_swiftcode=bnpa FR PP PLZ bill_address1=park bill_city=hinterbruhl bill_country=at branch_code=99999 currency=eur customer_firstname=john customer_lastname=smith customer_phone= date_collect= direct_debit_text=direct Debit Text direct_debit_type=001 grand_total_amount= mandate_id=1 merchant_id=mercid123 merchant_ref_number=merref123 Example 50 Standalone Direct Debit Refund Reply currency=eur direct_debit_refund_amount= direct_debit_refund_iban=ie64bofi direct_debit_refund_rcode=1 direct_debit_refund_rflag=sok direct_debit_refund_rmsg=request was processed successfully. direct_debit_refund_time= t211934z direct_debit_refund_trans_ref_no=reference No ics_rcode=1 ics_rflag=sok ics_rmsg=request was processed successfully. merchant_ref_number=merref123 request_id= Global Payment Service Developer Guide March

148 Chapter 10 Direct Debits and Direct Debit Refunds Using the SCMP API Direct Debit Refund Follow-On Example 51 Follow-On Direct Debit Refund Request ics_applications=ics_direct_debit_refund direct_debit_request_id= grand_total_amount=21.11 merchant_id=mercid123 merchant_ref_number=merref123 Example 52 Follow-On Direct Debit Refund Reply currency=eur direct_debit_refund_amount=21.11 direct_debit_refund_iban=ie64bofi direct_debit_refund_rcode=1 direct_debit_refund_rflag=sok direct_debit_refund_rmsg=request was processed successfully. direct_debit_refund_time= t211943z direct_debit_refund_trans_ref_no= ics_rcode=1 ics_rflag=sok ics_rmsg=request was processed successfully. merchant_ref_number=merref123 request_id= Global Payment Service Developer Guide March

149 Testing CHAPTER 11 Sending Test Requests You can send test requests for bank transfers, real-time bank transfers, direct debits, refunds, and mandates to the CyberSource test server. CyberSource performs the same basic validations that are performed for production transactions. For bank transfer replies, you receive fake bank account information. Test transactions are not forwarded to the payment processor. The requirements for test transactions are: Use your regular CyberSource merchant ID. Match the country and currency information. For example, if testing a bank transfer in Germany, make sure that you specify Germany as the bank country and the country of the customer s address, and specify EUR as the currency. When testing the Simple Order API, use the test URL: When testing the SCMP API, use the CyberSource test server: Testing Bank Transfers, Direct Debits, and Refunds You use specific amounts in your test transactions to trigger specific responses. This process enables you to easily generate the various responses that your system needs to handle. The following table shows the amounts and decline or error responses that are returned by the simulator. The tables include responses for both the Simple Order API (reason code) and the SCMP API (rflag and rmsg. Global Payment Service Developer Guide March

150 Chapter 11 Testing See Appendix B, "Reason Codes," on page 155 for descriptions of the Simple Order API reason codes. The rmsg you actually receive contains all capital letters with underscores between the words. Table 43 Test Data for Global Payment Service Amount Simple Order API Reason Code SCMP API rflag SCMP API rmsg Description Used with These Payment Types DINVALIDDATA No bank found for this country Bank Transfer DINVALIDDATA Invalid bank account number Bank Transfer Direct Debit DINVALIDDATA Invalid Post giro account number Bank Transfer Direct Debit DINVALIDDATA Authorization ID is required for country. Direct Debit DINVALIDDATA Bank code is required for country Direct Debit DINVALIDDATA Account name is required for country Direct Debit DINVALIDDATA Account number is required for country Direct Debit DINVALIDDATA Direct debit text is required for country Direct Debit DINVALIDDATA Date collect is required for country Direct Debit DINVALIDDATA Bank check digit is required for country Direct Debit DINVALIDDATA Branch code is required for country Direct Debit DINVALIDDATA Bank name is required for country Direct Debit DINVALIDDATA Date collected. Direct Debit DINVALIDDATA Account number has invalid length Direct Debit DINVALIDDATA Invalid bank code for payment type and country combination Direct Debit DINVALIDDATA Bank code does not match bank name Direct Debit DINVALIDDATA Invalid bank account number Bank Transfer Direct Debit DINVALIDDATA Invalid Post giro account number Bank Transfer DINVALIDDATA Amount not between minimum and maximum amounts Direct Debit Bank Transfer Direct Debit DINVALIDDATA Payment type invalid for country code Bank Transfer Direct Debit Global Payment Service Developer Guide March

151 Chapter 11 Testing Table 43 Test Data for Global Payment Service (Continued) Amount Simple Order API Reason Code SCMP API rflag SCMP API rmsg Description DINVALIDDATA Already refunded; no multiple refunds allowed Bank Transfer Refund Direct Debit Refund DINVALIDDATA Refund amount too large Bank Transfer Refund Direct Debit Refund ESYSTEM The request refers to an unknown order. Bank Transfer Refund ETIMEOUT Time-out connecting to processor All ESYSTEM Unexpected error All Used with These Payment Types Direct Debit Refund Testing Real-Time Bank Transfers Testing Your CyberSource Interface This stage of testing is available for all real-time bank transfer networks. Note Use the CyberSource simulator to test your interface with the CyberSource services. Send a real-time bank transfer request to CyberSource and make sure that you receive a realtime bank transfer reply from CyberSource. Important Do not use the URL that CyberSource returns to you in the reply message during this stage of testing. It is not a valid URL. Global Payment Service Developer Guide March

152 Chapter 11 Testing Testing Your Network Interface Note This stage of testing is available only for the real-time bank transfer networks in the following table. The purpose of network testing is to verify that you can redirect your customer s browser to the network. Table 44 Network Testing for Real-Time Bank Transfers Network enets GiroPay (Germany) ideal (Netherlands) Nordea e-betaling (Denmark) Nordea e-betalning (Sweden) Nordea e-maksu (Finland) Description It is not necessary to use special test account details for testing. The test payment pages are identical to the production version. Only DBS provides a valid test link; the other test links are down most of the time. The test page is available only in German. Special test cases are available. The test payment page is not identical to the production version. The test payment page provides a way to test the different flows. Special test cases are available. The test payment pages are not identical to the production version. Only a subset of the different flows can be tested. Payment pages are available only in Danish. The test payment pages are not identical to the production version. Only a subset of the various flows can be tested. Payment pages are available only in Swedish. The test payment pages are not identical to the production version. Only a subset of the various flows can be tested. Payment pages are available only in Finnish. The test payment pages are not identical to the production version. Only a subset of the various flows can be tested. To test your network interface: Step 1 Step 2 Step 3 Step 4 Step 5 Contact Customer Support to have your connection switched to the network s simulator. Set up a test customer that consists of a browser that interfaces with your shopping cart. Simulate the customer experience by having your test customer initiate a real-time bank transfer payment. When you receive this customer message, send a real-time bank transfer request to CyberSource. When you receive the real-time bank transfer reply from CyberSource, redirect the test customer to the network by using the URL in the reply message. Global Payment Service Developer Guide March

153 Chapter 11 Testing Step 6 Using the test customer browser, verify that you have received a page from the network. Going Live After successfully testing your account, you must go live with CyberSource before you begin accepting payments. When you go live, your CyberSource account is updated so that you can send transactions to the CyberSource production server. If you have not already done so, you will need to provide your payment processor and banking information to CyberSource so that your processor can deposit funds to your merchant bank account. For more information, see Getting Started with CyberSource Advanced for the Simple Order API or Getting Started with CyberSource Advanced for the SCMP API. Your production transactions will be available for you to view in the production version of the Business Center: Global Payment Service Developer Guide March

154 Product Codes APPENDIX A The following table lists the values that you can use for the product code. For the Simple Order API, use the item_#_productcode request field to specify the product code. For the SCMP API, use the product_code offer-level field. Table 45 Product Code Values Product Code adult_content coupon default electronic_good electronic_software gift_certificate handling_only service shipping_and_handling shipping_only subscription Definition Adult content. Coupon applied to the entire order. Default value for the product code. CyberSource uses default when a request provides no value for the product code. Electronic product other than software. Software distributed electronically rather than on tapes, disks, or other media. Gift certificate not issued with CyberSource Stored Value Services. Separate charge that is generally a fee imposed by the seller on the customer. The fee pays the seller s administrative selling costs. Service that you perform for the customer. Shipping is a separate charge for shipping the product to the purchaser. Handling is generally a fee imposed by the seller to pay administrative selling costs. Charge for transporting tangible personal property from the seller to the purchaser. Documentation must be maintained that clearly establishes where title to the tangible personal property passed from the seller to the purchaser. Subscription to a web site or other content. Global Payment Service Developer Guide March

155 Reason Codes APPENDIX B Reason Codes for the Simple Order API These reason codes apply only if you use the Simple Order API. The reason code appears in the reply that you receive immediately after you request the service. See Getting Started with CyberSource Advanced for the Simple Order API for a discussion of replies, decisions, and reason codes. Note CyberSource reserves the right to add new reason codes at any time. If your error handler receives a reason code that it does not recognize, it should use the decision field to obtain the result. Table 46 Reason Code Reason Codes for the Simple Order API Description 100 Successful transaction. 101 The request is missing one or more required fields. See the reply fields missingfield_0...n. Resend the request with the complete information. For more information about missing and invalid fields, see Getting Started with CyberSource Advanced for the Simple Order API. 102 One or more fields in the request contain invalid data. See the reply fields invalidfield_0...n. Resend the request with the correct information. For more information about missing and invalid fields, see Getting Started with CyberSource Advanced for the Simple Order API. 150 General system failure. See the documentation for your CyberSource client for information on handling retries in the case of system errors. Global Payment Service Developer Guide March

156 Appendix B Reason Codes Table 46 Reason Code Reason Codes for the Simple Order API (Continued) Description 151 The request was received but a server time-out occurred. This error does not include time-outs between the client and the server. To avoid duplicating the transaction, do not resend the request until you have reviewed the transaction status in the Business Center. See the documentation for your CyberSource client for information on handling retries in the case of system errors. 152 The request was received, but a service timed out. To avoid duplicating the transaction, do not resend the request until you have reviewed the transaction status in the Business Center. See the documentation for your CyberSource client for information on handling retries in the case of system errors. 231 Invalid account number. Request a different form of payment. 233 General decline by the processor. Request a different form of payment. 234 A problem exists with your CyberSource merchant configuration. Do not resend the request. Contact Customer Support to correct the configuration problem. 236 Processor failure. Wait a few minutes and resend the request. 239 The requested transaction amount must match the previous transaction amount. Correct the amount and resend the request. 241 The request ID is invalid. Verify the request ID is correct. 244 The bank account number failed the validation check. Verify with the customer that the account number is correct; if it was incorrect, request the service again with the corrected information. 248 When CyberSource sent a Boleto Bancário request to CyberSource Latin American Processing, the processor returned an error to CyberSource. 250 The request was received, but a time-out occurred with the payment processor. To avoid duplicating the transaction, do not resend the request until you have reviewed the transaction status in the Business Center. 254 Your CyberSource account is prohibited from processing stand-alone refunds. In the refund request, provide the requestid of the payment to create a follow-on refund. If you want to process stand-alone refunds, contact your CyberSource account representative. Global Payment Service Developer Guide March

157 Appendix B Reason Codes Table 46 Reason Code Reason Codes for the Simple Order API (Continued) Description 255 Your CyberSource account is not configured to process the service in the country you specified. If this is a bank transfer or bank transfer refund, check the billto_country value and bankinfo_country value to make sure they are set to the correct country (if it is a direct debit, check bankinfo_country). If you want to process the service in a country for which you are not configured, contact your CyberSource account representative. Global Payment Service Developer Guide March

158 Researching a Missing Bank Transfer Payment APPENDIX C This appendix explains how to submit an inquiry in the Business Center to research a missing bank transfer payment. For additional information, see: Simple Order API "Researching a Missing Payment," page 17 SCMP API "Researching a Missing Payment," page 35 Note Wait at least five days after funds are debited from a customer s account before initiating an inquiry because it can take that long for funds to appear in your account and in CyberSource s reports. CyberSource does not allow you to perform an inquiry within five days of submitting the initial bank transfer request. If your user permissions in the Business Center are limited to only read access for the Support Screens, you cannot research a missing payment. You must have additional access permissions. Contact your Business Center administrator to change your access level. Before making the inquiry, you must obtain the following items: Information about the bank account that the customer used to make the payment, including the name of the bank, the name on the customer s account, and the account number. The date that the funds were debited from the customer s account. A digital copy of a document that shows that the customer initiated the bank transfer (for example, a scanned bank statement or a screen shot of an online banking statement showing the payment). Global Payment Service Developer Guide March

159 Appendix C Researching a Missing Bank Transfer Payment To research a missing payment: Step 1 Step 2 Log in to the Business Center and search for the bank transfer transaction. View the transaction s details. If at least three days have passed since you sent the bank transfer request, Research Lost Payment appears as an available action. Step 3 Click Research Lost Payment. The Research Lost Payment page opens. Part of the form is already filled out with the original transaction information that CyberSource has. Global Payment Service Developer Guide March

160 Appendix C Researching a Missing Bank Transfer Payment Step 4 Step 5 In the Merchant Information section, enter your contact information. CyberSource uses this information to contact you if more information is needed. In the Customer s Bank Information section, enter the customer s bank s information and the payment date (the date that the funds were debited from the customer s account). The required fields are in bold. Step 6 Step 7 Step 8 In the Attachment field, attach the scanned copy of the customer s bank statement or whatever proof the customer has to show that they made the payment. In the Other Information field, include any other information that might help CyberSource research the missing payment. Click Submit to submit the information to CyberSource. A confirmation page opens, and the transaction details are updated to show that you have made a payment inquiry. Customer Support receives the inquiry information and contacts the processor to determine whether the processor received the payment. One of two things happens within several business days: The processor uses the inquiry information to match the payment to the original bank transfer request. Confirmation of the bank transfer payment then automatically appears in the Payment Events Report. The transaction details screen in the Business Center is also updated to show that the bank transfer has been paid. CyberSource does not contact you by or phone to give you the results, so you should monitor the Payment Events Report or the transaction s details in the Business Center. If the processor is unable to find or match the funds to the original bank transfer request, CyberSource contacts you by or phone. Global Payment Service Developer Guide March

161 INDEX Index A B C D E F G H I J K L M N O P Q R S T U V W X Y Z B bank account validation bank transfer refunds SCMP API 35 Simple Order API 17 direct debit refunds SCMP API 134 Simple Order API 117 direct debits SCMP API 132 Simple Order API 116 bank transfer refunds SCMP API 34 Simple Order API 16 bank transfers and bank transfer refunds SCMP API 33 Simple Order API 15 examples SCMP API 46 Simple Order API 28 requesting SCMP API 33 Simple Order API 15 unpaid 158 bank transfers, real-time. See real-time bank transfers banktransferrealtimeservice 54 banktransferrefundservice 16 banktransferservice 15 boletopaymentservice 84 Boletos Bancários description of C SCMP API 90 Simple Order API 84 reports Boleto Bancário Unfulfilled Report 96 Single Transaction Report 112 requesting SCMP API 90 Simple Order API 84 check reference numbers 13 coupons 154 D date and time format Simple Order API 27 direct debit refunds SCMP API 133 Simple Order API 116 direct debits and direct debit refunds SCMP API 132 Simple Order API 115 examples SCMP API 95 Simple Order API 88, 128, 145 requesting SCMP API 132 Simple Order API 115 directdebitrefundservice 116 directdebitservice 115 Global Payment Service Developer Guide March

162 Index A B C D E F G H I J K L M N O P Q R S T U V W X Y Z E examples bank transfers SCMP API 46 Simple Order API 28 direct debits SCMP API 95 Simple Order API 88, 128, 145 on-demand queries for failed payments SCMP API 70 Simple Order API 54 on-demand queries for successful payments SCMP API 69 Simple Order API 53 on-demand queries for transaction status SCMP API 68 Simple Order API 52 real-time bank transfers SCMP API 81 Simple Order API 64 F follow-on refunds for bank transfers SCMP API 34 Simple Order API 16 for direct debits SCMP API 133 Simple Order API 116 G GMT format Simple Order API 27 I ics_bank_transfer 33 ics_bank_transfer_real_time 70 ics_bank_transfer_refund 34 ics_boleto_payment 90 ics_direct_debit 132 ics_direct_debit_refund 133 M missing payments, researching 17 O on-demand queries real-time bank transfers SCMP API 67 Simple Order API 51 order tracking 13 P POST requests transaction statuses for SCMP API 67 Simple Order API 51 processor transaction identifiers 13 product codes listed 154 R real-time bank transfers examples SCMP API 81 Simple Order API 64 examples of on-demand queries for failed payments SCMP API 70 Simple Order API 54 examples of on-demand queries for successful payments SCMP API 69 Simple Order API 53 examples of on-demand queries for transaction status SCMP API 68 Simple Order API 52 refunds SCMP API 71 Simple Order API 55 Global Payment Service Developer Guide March

163 Index A B C D E F G H I J K L M N O P Q R S T U V W X Y Z requesting SCMP API 70 Simple Order API 54 transaction statuses SCMP API 67 Simple Order API 51 reason codes listed 155 reconciliation IDs 13 refunds bank transfers SCMP API 34 Simple Order API 16 direct debits SCMP API 133 Simple Order API 116 real-time bank transfers SCMP API 71 Simple Order API 55 reports Transaction Exception Detail Report for bank transfers, SCMP API 35 for bank transfers, Simple Order API 17 for direct debits, SCMP API 134 for direct debits, Simple Order API 117 request IDs 13 SCMP API 134 Simple Order API 117 transaction reference numbers 13 U UTC format Simple Order API 27 S statuses of real-time bank transfers SCMP API 67 Simple Order API 51 T test server 149 time format Simple Order API 27 Transaction Exception Detail Report for bank transfers SCMP API 35 Simple Order API 17 for direct debits Global Payment Service Developer Guide March