Global Payment Service Developer Guide

Transcription

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 94128-8999 | Phone: 800-530-9095
CyberSource Contact Information
For general information about our company, products, and services, go to
http://www.cybersource.com.
For sales questions about any CyberSource Service, email [email protected] or
call 650-432-7350 or 888-330-2300 (toll free in the United States).
For support information about any CyberSource Service, visit the Support Center at
http://www.cybersource.com/support.
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
252.227-7013 and in similar clauses in the FAR and NASA FAR Supplement.
For civilian agencies. Use, reproduction, or disclosure is subject to restrictions set forth in subparagraphs (a)
through (d) of the Commercial Computer Software Restricted Rights clause at 52.227-19 and the limitations 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
CONTENTS
Contents
Recent Revisions to This Document
About This Guide
8
10
Audience and Purpose
10
Conventions 10
Note and Important Statements 10
Text and Command Conventions 10
Related Documents
Chapter 1
11
Customer Support
11
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
Request IDs 14
Payment Reference Numbers 14
Chapter 2
13
Bank Transfers and Bank Transfer Refunds Using the Simple Order API
Requesting Bank Transfers
15
15
Requesting Bank Transfer Refunds
Researching a Missing Payment
16
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 2015
3
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
33
Requesting Bank Transfer Refunds
34
35
API Fields 36
Request Fields 36
Offer-Level Fields 41
Reply Fields 42
Reply Flags 45
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
API Fields 55
Request Fields 55
Bank Codes 60
Reply Fields 61
Additional Request Fields
63
Real-Time Bank Transfer Request 64
Real-Time Bank Transfer Reply 65
Real-Time Bank Transfer Refund 65
Real-Time Bank Transfer Refund Reply
55
66
4
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
API Fields 71
Request Fields 71
Bank Codes 76
Reply Fields 78
Reply Flags 79
71
80
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
Requesting a Boleto Bancário
API Fields 84
Data Type Definitions
Request Fields 85
Reply Fields 86
84
84
84
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
90
API Fields 90
Request Fields 90
Reply Fields 92
Reply Flags 94
Request and Reply Examples
Request 95
Reply 95
95
5
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
Chapter 9
112
Direct Debits and Direct Debit Refunds Using the Simple Order API
Requesting Direct Debits
115
115
Requesting Direct Debit Refunds
116
API Fields 118
Request Fields 118
Reply Fields 126
Direct Debit Request 128
Direct Debit Reply 129
Standalone Direct Debit Refund Request
Follow-On Direct Debit Refund 130
Chapter 10
129
Direct Debits and Direct Debit Refunds Using the SCMP API
132
132
133
API Fields 135
Request Fields 135
Reply Fields 142
Reply Flags 144
Direct Debit Request 145
Direct Debit Refund—Standalone 147
Direct Debit Refund—Follow-On 148
6
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
Index
158
161
7
REVISIONS
Recent Revisions to This
Document
Release
Changes
March 2015

Updated Example 15. See page 54.

Updated Example 22. See page 70.
January 2015
Removed the Interac processor from the document.
December 2014
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:

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:

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
8
Recent Revisions to This Document
Release
Changes
September 2014
This revision contains only editorial changes and no technical updates.
August 2014
Removed the following request fields for direct debits and direct debit
refunds:
July 2014

directDebitService_mandateID

direct_debit_mandate_id
Added examples to the following sections:

Bank transfers
 Simple Order API— page 28.


Real-time bank transfers
 Simple Order API—page 64.


SCMP API—page 46.
SCMP API—page 81.
Direct debits
 Simple Order API—page 128.

SCMP API—page 145.
9
ABOUT GUIDE
About This 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
A Note contains helpful suggestions or references to material not contained in
the document.
Note
An Important statement contains information essential to successfully
completing a task or learning a concept.
Important
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.
10
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:
http://www.cybersource.com/support_center/support_documentation
Customer Support
For support information about any CyberSource service, visit the Support Center:
http://www.cybersource.com/support
11
CHAPTER
1
Getting Started
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
Version
Boletos Bancários
1.42 or later
Real-time bank transfers
1.23 or later
12
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
Payment Method
Service
Field Names
Bank transfers
Bank transfer

Simple Order API: bankTransferReply_reconciliationID

SCMP API: bank_transfer_trans_ref_no
Bank transfer
refund

Simple Order API: bankTransferRefundReply_reconciliationID

SCMP API: bank_transfer_refund_trans_ref_no
Real-time bank
transfer

Simple Order API: bankTransferRealTimeReply_
reconciliationID

SCMP API: bank_transfer_real_time_trans_ref_no
Boleto Bancário
payment

Simple Order API: boletoPaymentReply_reconciliationID

SCMP API: boleto_payment_trans_ref_no
Direct debit

Simple Order API: directDebitReply_reconciliationID

SCMP API: direct_debit_trans_ref_no

Simple Order API: directDebitRefundReply_reconciliationID

SCMP API: direct_debit_refund_trans_ref_no
Boletos Bancários
Direct debits
Direct debit refund
13
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
Payment Method
Service
Field Names
Bank transfers
Bank transfer
refund for a bank
transfer

Simple Order API:
bankTransferRefundService_bankTransferRequestID

SCMP API: bank_transfer_request_id
Bank transfer
refund for a realtime bank transfer

Simple Order API:
bankTransferRefundService_
bankTransferRealTimeRequestID

SCMP API: bank_transfer_real_time_request_id

Simple Order API: directDebitRefundService_
directDebitRequestID

SCMP API: direct_debit_request_id
Direct debits
Direct debit refund
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

Simple Order API: bankTransferRealTimeReply_
paymentReference

SCMP API: bank_transfer_real_time_payment_reference
Real-time bank
transfer
14
CHAPTER
Bank Transfers and Bank
Transfer Refunds Using the
Simple Order API
2
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.
15
Chapter 2
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, 2016.
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.
16
Chapter 2

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.
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.
17
Chapter 2
API Fields
For information about the data types, see Getting Started with CyberSource Advanced for
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
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 (See
description)
String (See
description)
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.
bankInfo_branchCode
Code that identifies the branch of the
customer's bank when you are not using
the IBAN.
Refund (O)
String (15)
bankInfo_city
City in which the bank is located.
Refund (O)
String (40)
Bank Transfer
(See description)
String (2)
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.
bankInfo_country
Country in which the bank is located. Use
the two-character ISO Standard Country
Codes.
Refund (R)
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
18
Chapter 2
Table 5
for the Simple Order API (Continued)
Request Field
Description
Used By and
Required (R) or
Optional (O)
Data Type
& Length
bankInfo_name
Bank's name.
Refund (See
description)
String (40)
Bank Transfer (O)
String (30)
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.
bankInfo_swiftCode
Bank’s SWIFT code. Unique address of
the bank. Also known as the Bank
Identification Code (BIC).
Refund (O)
Note This field is required when the
IBAN is included in the request.
bankTransferRequestID
The requestID value returned from a
previous request for the bank transfer
service.
Refund (R)
String (26)
reconciliationID
Unique identifier for the order submitted to
Global Collect.
Refund (R for
standalone
refunds)
String (60)
Note If you do not include this field in a
refund request, CyberSource will
generate the value.
run
Set to true to include the bank transfer
refund service in your request.
Refund (R)
String (5)
bankTransferService_run
Set to true to include the bank transfer
service in your request.
Bank Transfer (R)
String (5)
billTo_city
City of the billing address.
Bank Transfer (R)
String (50)
Refund (R)
billTo_company
Name of the customer’s company.
Bank Transfer (O)
String (60)
billTo_country
Billing address country. Use the ISO
Standard Country Codes.
Bank Transfer (R)
String (2)
Customer’s email address, including the
full domain name. For example:
[email protected]
Bank Transfer (R)
Customer’s first name.
Bank Transfer (R)
billTo_email
billTo_firstName
Refund (R)
String (255)
Refund (R)
String (60)
Refund (R)
billTo_lastName
Customer’s last name.
Bank Transfer (R)
String (60)
Refund (R)
19
Chapter 2
Table 5
Request Field
Description
Used By and
Required (R) or
Optional (O)
Data Type
& Length
billTo_phoneNumber
Customer’s telephone number.
Bank Transfer (O)
String (15)
Refund (O)
billTo_postalCode
Postal code for the billing address. The
postal code must consist of 5 to 9 digits.
Bank Transfer (R)
String (10)
Refund (R)
If the value of billTo_country is US, the
9-digit postal code must follow this format:
[5 digits][dash][4 digits]
Example: 12345-6789
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
billTo_state
Billing address state.
Bank Transfer
(R)1
String (2)
Refund (R)1
billTo_street1
Billing address street address.
Bank Transfer (R)
String (60)
Refund (R)
billTo_street2
Additional address information.
Bank Transfer (O)
String (60)
Refund (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.
Refund (O)
String (50)
Contact CyberSource Customer Support
for required country-specific bank account
information.
20
Chapter 2
Table 5
Request Field
Description
Used By and
Required (R) or
Optional (O)
Data Type
& Length
fundTransfer_accountNumber
Bank account number.
Refund (O)
String (See
description)
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, 2016.
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.
Refund (O)
String (2)
fundTransfer_iban
International Bank Account Number
(IBAN) for the bank account.
Refund (See
description)
String (30)
Bank Transfer (O)
String (30)
Note Required for specific countries.
Contact CyberSource Customer Support
information.
item_#_productCode
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.
Refund (O)
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.
Bank Transfer
(See description)
String (30)
Refund (O)
21
Chapter 2
Table 5
Request Field
Description
Used By and
Required (R) or
Optional (O)
Data Type
& Length
item_#_productSKU
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.
Bank Transfer
(See description)
String (30)
Quantity of the product being purchased.
For bank transfers, required if item_#_
productCode is NOT default,
Bank Transfer
(See description)
Tax amount associated with this item. The
item_#_taxAmount field is additive. For
example, if you send one item with
unitPrice of 10.00 and taxAmount of
0.80, and you send another item with
unitPrice of 20.00 and taxAmount of
1.60, the total amount authorized will be
for 32.40, not 30.00 with 2.40 of tax
included.
Bank Transfer (O)
item_#_quantity
item_#_taxAmount
Refund (O)
Integer (10)
Refund (O)
String (15)
Refund (O)
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.
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, see
Getting Started with CyberSource
Advanced for the Simple Order API.
Bank Transfer
String (15)
Refund
(See description)
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.
22
Chapter 2
Table 5
Request Field
Description
Used By and
Required (R) or
Optional (O)
Data Type
& Length
linkToRequest
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.
Bank Transfer (O)
String (26)
merchantID
Your CyberSource merchant ID.
Bank Transfer (R)
String (30)
Note When opening your account with
Refund (R)
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
Bank Transfer (R)
Currency used for the order. Use the ISO
Standard Currency Codes.
Bank Transfer (R)
Grand total for the order. You must include
either this field or item_#_unitPrice in
your request. For more information, see
Bank Transfer
shipTo_city
City of the shipping address.
Bank Transfer
(O)2
String (50)
shipTo_country
Country of the shipping address. Use the
two-character ISO Standard Country
Codes.
Bank Transfer (O)
String (2)
shipTo_firstName
First name of the person receiving the
product.
Bank Transfer (O)
String (60)
shipTo_lastName
Last name of the person receiving the
product.
Bank Transfer (O)
String (60)
merchantReferenceCode
purchaseTotals_currency
purchaseTotals_
grandTotalAmount
String (50)
Refund (R)
String (5)
Refund (R)
String (15)
Refund
See description
23
Chapter 2
Table 5
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
Postal code for the shipping address. The
Bank Transfer
(O)3
String (10)
If the value of shipTo_country is US, the
9-digit postal code must follow these
rules:
Example: 12345-6789
If the value of shipTo_country is CA, the
6-digit postal code must follow these
rules:
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.
shipTo_state
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 (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)
24
Chapter 2
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
Reply Field
Description
Returned By
Data Type
& Length
bankTransferRefundReply_
amount
Total amount for the bank transfer refund.
Refund
String (15)
iban
International Bank Account Number (IBAN)
for the bank account.
Refund
Alphanumeric
(50)
processorResponse
Response code from the processor.
Refund
String (10)
reasonCode
A numeric value corresponding to the result
of the bank transfer refund request. See
"Reason Codes," page 155, for a list of
possible values.
Refund
Integer (5)
reconciliationID
Unique value generated by CyberSource. For
more information, see Getting Started with
CyberSource Advanced for the Simple Order
API.
Refund
String (60)
requestDateTime
Time the bank transfer refund was requested.
Format: YYYY-MM-DDThh:mm:ssZ.
Example: 2007-08-11T22: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
String (20)
bankTransferReply_
accountHolder
Name of the account holder.
Bank Transfer
String (50)
bankTransferReply_
accountNumber
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.
Bank Transfer
String (30)
Contact CyberSource Customer Support for
information.
bankTransferReply_amount
Total amount for the bank transfer.
Bank Transfer
String (15)
bankTransferReply_bankCity
Bank Transfer
String (50)
bankTransferReply_
bankCountry
Country in which the bank is located.
Bank Transfer
String (50)
25
Chapter 2
Table 6
Reply Field
Description
Returned By
Data Type
& Length
bankTransferReply_
bankName
Name of the bank.
Bank Transfer
String (50)
bankTransferReply_
bankSpecialID
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
Bank Transfer
String (50)
bankTransferReply_
bankSwiftCode
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.
Bank Transfer
String (50)
bankTransferReply_iban
for the bank account. If this field is in the
reply, display the value to the customer along
with the other bank information.
Bank Transfer
String (30)
Note Required for specific countries.
information.
bankTransferReply_
paymentReference
Payment reference number that you must
display to the customer. For more
information, see Getting Started with
API. In Italy, this is called the Numero di
riferimento.
Bank Transfer
String (16)
bankTransferReply_
processorResponse
Bank Transfer
String (10)
bankTransferReply_
reasonCode
A numeric value corresponding to the result
of the bank transfer request. See "Reason
Codes," page 155, for a list of possible
values.
Bank Transfer
Integer (5)
bankTransferReply_
reconciliationID
Unique value generated by CyberSource. For
API.
Bank Transfer
String (60)
26
Chapter 2
Table 6
Reply Field
Description
Returned By
Data Type
& Length
bankTransferReply_
requestDateTime
Time the bank transfer was requested.
Example: 2005-08-11T22: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.
Bank Transfer
String (20)
decision
Summarizes the result of the overall request.
Possible values:
Bank Transfer
and Refund
String (6)

ACCEPT

ERROR

REJECT
invalidField_0...N
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.
Bank Transfer
and Refund
String (100)
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.
Bank Transfer
and Refund
String (50)
missingField_0...N
Required fields that were missing from the
request. These reply fields are included as an
Getting Started with CyberSource Advanced
for the Simple Order API.
Bank Transfer
and Refund
String (100)
Currency used for the order. Uses the ISO
Bank Transfer
and Refund
String (5)
reasonCode
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
Integer (5)
requestID
Identifier for the request.
Bank Transfer
and Refund
String (26)
27
Chapter 2
Bank Transfer Request
Example 1
<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>[email protected]</email>
</billTo>
<bankInfo>
<bankCountry>NL</bankCountry>
<bankCity>Amsterdam</bankCountry>
<bankName>ABN Amro Bank N.V</bankName>
<swiftCode>ABNA NL 2A</swiftCode>
</bankInfo>
<fundTransfer>
<accountNumber>440339464</accountNumber>
</fundTransfer>
<item id="0">
<unitPrice>49.95</unitPrice>
<quantity>1</quantity>
</item>
<purchaseTotals>
<currency>GBP</currency>
</purchaseTotals>
<bankTransferService run="true"/>
</requestMessage>
28
Chapter 2
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>0305782650000167905080</c:requestID>
<c:decision>ACCEPT</c:decision>
<c:reasonCode>100</c:reasonCode>
<c:purchaseTotals>
<c:currency>EUR</c:currency>
</c:purchaseTotals>
<c:bankTransferReply>
<c:accountHolder>Global Collect BV</c:accountHolder>
<c:accountNumber>440339464</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>106157214759</c:paymentReference>
<c:bankSwiftCode>ABNA NL 2A</c:bankSwiftCode>
<c:bankSpecialID>20-00-00</c:bankSpecialID>
<c:requestDateTime>2012-01-28T23:44:27Z</c:requestDateTime>
<c:reconciliationID>0308014624</c:reconciliationID>
</c:bankTransferReply>
</c:replyMessage>
29
Chapter 2
Standalone Bank Transfer Refund Request
Example 3
<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>33 3 69 20 45 63</phoneNumber>
</billTo>
<purchaseTotals>
<currency>EUR</currency>
<grandTotalAmount>112</grandTotalAmount>
</purchaseTotals>
<fundTransfer>
<accountName>BRADFORD NICKLES</accountName>
</fundTransfer>
<bankInfo>
<bankCode>79050000</bankCode>
<name>SloveniaBank_testing</name>
<swiftCode>BSLJSI2X</swiftCode>
</bankInfo>
<bankTransferRefundService run="true">
<reconciliationID>33552111</reconciliationID>
</bankTransferRefundService>
</requestMessage>
30
Chapter 2
Standalone Bank Transfer Refund Reply
Example 4
<c:merchantReferenceCode>demoRef</c:merchantReferenceCode>
<c:purchaseTotals>
<c:currency>eur</c:currency>
</c:purchaseTotals>
<c:bankTransferRefundReply>
<c:iban>DE58790500000044497071</c:iban>
</c:bankTransferRefundReply>
</c:replyMessage>
Follow-On Bank Transfer Refund Request
Example 5
<billTo>
</billTo>
<purchaseTotals>
</purchaseTotals>
<fundTransfer>
</fundTransfer>
31
Chapter 2
<bankInfo>
</bankInfo>
<bankTransferService run="true"/>
</requestMessage>
Follow-On Bank Transfer Refund Reply
Example 6
<c:purchaseTotals>
</c:purchaseTotals>
<c:bankTransferReply>
<c:accountHolder>Global Collect B.V.</c:accountHolder>
<c:accountNumber>115241904</c:accountNumber>
<c:bankName>Postbank AG</c:bankName>
<c:bankCity>Leipzig</c:bankCity>
<c:bankCountry>Germany</c:bankCountry>
<c:bankSwiftCode>PBNKDEFF</c:bankSwiftCode>
<c:bankSpecialID>BLZ|86010090</c:bankSpecialID>
<c:iban>DE53860100900115241904</c:iban>
</c:bankTransferReply>
</c:replyMessage>
32
CHAPTER
Bank Transfers and Bank
Transfer Refunds Using the
SCMP API
3
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.
33
Chapter 3
Requesting Bank Transfer
Refunds
Important
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
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.

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,
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.
34
Chapter 3

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
You will not receive an error in the reply for any of the following conditions:

The bank_transfer_request_id is invalid.

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.
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.
35
Chapter 3
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
Description
Used by and
Required (R) or
Optional (O)
Data Type
& Length
bank_account_name
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.
Refund (O)
String (50)
Refund (O)
String (See
description)
Refund (O)
String (255)
information.
bank_account_
number
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, 2016.
Note Do not use the IBAN in this field. Use only
the traditional account number information. For the
IBAN, use the bank_iban field.
bank_address
Bank’s address.
1. Required if bill_country value is US or CA
3. Required if ship_to_country value is US or CA
36
Chapter 3
Table 7
for the SCMP API (Continued)
Request-Level
Field
Description
Used by and
Required (R) or
Optional (O)
Data Type
& Length
bank_check_digit
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.
Refund (O)
String (2)
bank_city
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.
Refund (O)
String (40)
bank_code
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 (See
description)
String (See
description)
Country where the bank is located. Use the twocharacter ISO Standard Country Codes.
Bank Transfer (See
description)
String (2)
Note If bank_country is not set, CyberSource
Refund (R)
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.
bank_country
uses bill_country to determine the country in
which the bank transfer is taking place.
bank_iban
Refund (See
description)
String (30)
Refund (See
description)
String (40)
Bank’s SWIFT code. Unique address of the bank.
Also known as the Bank Identification Code (BIC).
Bank Transfer (See
description)
String (30)
Note This field is required when the IBAN field is
Refund (O)
International Bank Account Number (IBAN) for the
bank account.
Note Required for specific countries. Contact
country-specific bank account information.
bank_name
Bank's name.
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_swiftcode
included in the request.
bank_transfer_
request_id
The request_id value returned from a previous
request for ics_bank_transfer.
Refund (R)
String (26)
37
Chapter 3
Table 7
Request-Level
Field
Description
Used by and
Required (R) or
Optional (O)
Data Type
& Length
bank_transfer_trans_
ref_no
Unique identifier for the order submitted to Global
Collect.
Refund (R for
standalone refunds)
String (60)
Bank Transfer (R)
String (60)
Note If you do not include this field in a refund
request, CyberSource will generate the value.
bill_address1
Billing street address.
Refund (R)
bill_address2
Additional billing address information.
Bank Transfer (O)
String (60)
Refund (O)
bill_city
Billing address city.
Bank Transfer (R)
String (50)
Refund (R)
bill_country
Billing address country.
Bank Transfer (R)
String (2)
Refund (R)
bill_state
Billing address state.
Bank Transfer (R) 1
Refund (R)
bill_zip
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:
Example:12345-6789
String (2)
1
Bank Transfer (R if
bill_country is US
or CA)
String (10)
Refund (R if bill_
country is US or
CA)
If the value of bill_country is CA, the 6-digit zip
Example: A1B 2C3
branch_code
Code that identifies the branch of the customer's
bank when you are not using the IBAN.
Refund (O)
String (15)
information.
company_name
Bank Transfer (O)
String (60)
currency
Currency used for the order. Use the ISO Standard
Currency Codes.
Bank Transfer (R)
String (5)
Customer’s email address. For example:
[email protected]
Bank Transfer (R)
customer_email
Refund (R)
String (255)
Refund (R)
38
Chapter 3
Table 7
Request-Level
Field
Description
Used by and
Required (R) or
Optional (O)
Data Type
& Length
customer_firstname
Bank Transfer (R)
String (60)
Refund (R)
customer_lastname
Bank Transfer (R)
String (60)
Refund (R)
customer_phone
Bank Transfer (O)
String (15)
Refund (O)
grand_total_amount
ics_applications
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.
Bank Transfer
ICS services to process for the request.
Bank Transfer (R)
Refund
Decimal
(15)
See description
String (255)
Refund (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
details, see the information about partial
authorizations in Credit Card Services Using the
SCMP API.
Bank Transfer (O)
String (26)
merchant_id
Bank Transfer (R)
String (30)
Refund (R)
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,
merchant_ref_
number
Merchant-generated order reference or tracking
number. See the information about tracking orders
in Getting Started with CyberSource Advanced for
the SCMP API.
Bank Transfer (R)
offer0...N
Offers for the request. An offer is a line item for the
order.
Bank Transfer (O)
String (50)
Refund (R)
String (50)
Refund (O)
39
Chapter 3
Table 7
Request-Level
Field
Description
Used by and
Required (R) or
Optional (O)
Data Type
& Length
ship_to_address1
First line of the address to which to ship the
product.
Bank Transfer (O) 2
String (60)
ship_to_address2
Second line of the address to which to ship the
product.
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
Bank Transfer (O)
String (15)
3
ship_to_state
State or province to which to ship the product. Use
the State, Province, and Territory Codes for the
United States and Canada.
Bank Transfer (O)
ship_to_zip
Zip code for the shipping address.
Bank Transfer (O) 3
String (10)
Bank Transfer (O)
Positive
integer (3)
String (2)
If the value of ship_to_country is US, the 9-digit
zip code must follow this format:
Example: 12345-6789
If the value of ship_to_country is CA, the 6-digit
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
timeout
Number of seconds until the transaction times out.
The default is 110 seconds.
Refund (O)
40
Chapter 3
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 description)
Decimal (15)
Refund
(See description)
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_code
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
description)
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)
String (30)
Refund (O)
String (30)
Refund (O)
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
quantity
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
description)
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
description)
String (30)
Refund (O)
Refund (O)
Nonnegative
integer (10)
41
Chapter 3
Table 8
Offer-Level Fields for Bank Transfers and Bank Transfer Refunds
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)
Decimal (15)
Refund (O)
offer0=amount:10.00^
quantity:1^tax_amount:0.80
the total amount authorized will be for 32.40, not
30.00 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.
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
Bank Transfer
String (50)
bank_transfer_bank_
country
Bank Transfer
String (50)
42
Chapter 3
Table 9
Reply Field
Description
Returned
By
Data Type
& Length
bank_transfer_bank_
name
Bank’s name.
Bank Transfer
String (50)
bank_transfer_iban
bank account. If this field is in the reply, display the
value to the customer along with the other bank
information.
Bank Transfer
String (30)
Note Contact CyberSource Customer Support for
required country-specific bank account information.
bank_transfer_
payment_reference
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.
Bank Transfer
String (16)
bank_transfer_rcode
One-digit code that indicates whether the ics_
bank_transfer request was successful.
Bank Transfer
Integer (1)
bank_transfer_refund_
amount
Amount of the bank transfer refund.
Refund
Decimal (15)
bank_transfer_refund__
iban
bank account.
Refund
Alphanumeric
(50)
rcode
One-digit code that indicates whether the ics_
bank_transfer_refund request was successful.
Refund
Integer (1)
response_code
Refund
String (10)
rflag
One-word description of the result of the ics_bank_
transfer_refund request.
Refund
String (50)
rmsg
Message that explains the reply flag bank_
transfer_refund_rflag.
Refund
String (255)
time
Time of bank transfer refund request in UTC format.
For more information, see Getting Started with
Refund
Date and
time (20)
trans_ref_no
Unique value generated by CyberSource. See the
information about tracking orders in Getting Started
with CyberSource Advanced for the SCMP API.
Refund
String (60)
bank_transfer_request_
time
Time of the bank transfer request in UTC format. For
Bank Transfer
Date and
time (20)
bank_transfer_
response_code
Bank Transfer
String (10)
bank_transfer_rflag
transfer request.
Bank Transfer
String (50)
bank_transfer_rmsg
Message that explains the reply flag bank_
transfer_rflag.
Bank Transfer
String (255)
43
Chapter 3
Table 9
Reply Field
Description
Returned
By
Data Type
& Length
bank_transfer_special_
id
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
information.
Bank Transfer
String (50)
bank_transfer_swiftcode
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.
Bank Transfer
String (50)
bank_transfer_trans_
ref_no
Unique value generated by CyberSource. For more
information, see Getting Started with CyberSource
Bank Transfer
String (60)
client_lib_version
Information about the client library used to request
the transaction.
Bank Transfer
and Refund
String (50)
currency
Currency used for the order. Uses the ISO Standard
Currency Codes.
Bank Transfer
and Refund
String (5)
ics_rcode
One-digit code that indicates whether the entire
request was successful. The field will contain one of
the following values:
Bank Transfer
and Refund
Integer (1)

-1: An error occurred

0: The request was declined

1: The request was successful
ics_rflag
One-word description of the result of the entire
request.
Bank Transfer
and Refund
String (50)
ics_rmsg
Message that explains the reply flag ics_rflag.
Bank Transfer
and Refund
String (255)
merchant_ref_number
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
String (50)
request_id
Identifier for the request generated by CyberSource.
Bank Transfer
and Refund
String (26)
44
Chapter 3
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.
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.
ETIMEOUT
The request timed out.
SOK
The transaction was successful.
45
Chapter 3
Example 7
bill_address1=Boschdijk 987
bill_city=Eindhoven
bill_country=NL
bill_zip=5600 PB
currency=EUR
[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=440339464
ics_applications=ics_bank_transfer
merchant_id=infodev
merchant_ref_number=482046C3A7E94F5BD1FE3C66C
offer0=amount:49.95^quantity:1
46
Chapter 3
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=0305782650000167905080
bank_transfer_trans_ref_no=0308014624
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=2003-08-22T170910Z
bank_transfer_payment_reference=106157214759
bank_transfer_response_code=800
bank_transfer_special_id=20-00-00
bank_transfer_account_number=440339464
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
47
Chapter 3
Example 9
ics_applications=ics_bank_transfer_refund
bank_account_name=nette
bank_account_number=30004 00819 00010023116 61
bank_check_digit=12
bank_city=Paris
bank_code=0440339464
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=1234567890ABCDE
currency=EUR
[email protected]
customer_firstname=antoi
customer_lastname=nette
customer_phone=33-04-9208-2846
merchant_id=mercid123
merchant_ref_number=merRef123
offer0=product_code:electronic_software^merchant_product_
sku:testdl^quantity:1âmount:1.56^tax_amount:0.25^product_
name:PName1ôffer_id:0
request_id=4024360078230179087451
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
48
Chapter 3
Example 10
bank_transfer_refund_amount=1.81
bank_transfer_refund_iban=IE64BOFI30004 00819 00010023116 61
bank_transfer_refund_rcode=1
bank_transfer_refund_rflag=SOK
bank_transfer_refund_rmsg=Request was processed successfully.
bank_transfer_refund_time=2014-06-10T213327Z
bank_transfer_refund_trans_ref_no=2147997003
currency=eur
ics_rcode=1
ics_rflag=SOK
request_id=4024360078230179087451
Example 11
bank_check_digit=12
bank_city=Paris
bank_country=France
bank_swiftcode=BNPA FR PP PLZ
bank_transfer_request_id=4024360037900179087451
bill_country=FR
bill_zip=06513
currency=EUR
[email protected]
request_id=4024360039900179087451
sender_id=gc_btr_sepa_1
49
Chapter 3
ship_to_country=US
ship_to_zip=47404
Example 12
bank_transfer_account_holder=Global Collect BV
bank_transfer_account_number=30004 00819 00010023116 61
bank_transfer_amount=1.81
bank_transfer_bank_city=Paris
bank_transfer_bank_country=France
bank_transfer_bank_name=BNP Paribas
bank_transfer_iban=FR7630004008190001002311661
bank_transfer_payment_reference=140243600385
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=2014-06-10T213323Z
50
CHAPTER
Real-Time Bank Transfers
Using the Simple Order API
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.
For China, real-time bank transfer settlements are not posted until the next
business day.
Note
Sending the Query
To send the query, send the fields described in the following table in an HTTP POST
request to the following URL:
https://ebc.cybersource.com/ebc/Query
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
R
String (30)
Type of query. The only possible value is
R
String (30)
type
transaction.
subtype
Query subtype. The only possible value is
transactionStatus.
R
String (30)
requestID
Request ID returned in the real-time bank
transfer reply.
R
String (26)
51
Chapter 4
Table 11
Required Data for an On-Demand Transaction Status Query (Continued)
Field
Description
Required (R)
or Optional (O)
Data Type
& Length
transRefNo
Transaction reference number (SCMP
API) or reconciliation ID (Simple Order
API) returned in the real-time bank
transfer reply.
R
String (60)
requestToken
Request token data generated by
CyberSource for each transaction reply.
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="https://ebc.cybersource.com/ebc/Query" 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>
52
Chapter 4
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
<!ELEMENT
<!ELEMENT
<!ELEMENT
<!ELEMENT
<!ELEMENT
<!ELEMENT
<!ELEMENT
<!ELEMENT
xml (Request, Response)>
Request (MerchantID, RequestID, RequestDate)>
MerchantID (#PCDATA)>
RequestID (#PCDATA)>
RequestDate (#PCDATA)>
Response (PaymentStatus?)>
PaymentStatus (Status, ProcessorMessage?)>
Status (#PCDATA)>
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>4146924260000171399092</RequestID>
<RequestDate>Oct 30, 2014</RequestDate>
<Response>
<PaymentStatus>
<Status>Payment</Status>
<ProcessorMessage>The payment instruction has been accepted.
</ProcessorMessage>
</PaymentStatus>
</Response>
</Request>
</xml>
53
Chapter 4
This example shows on-demand query results for a failed real-time bank transfer
payment.
Example 15
Failed Payment
<xml>
<Request>
<MerchantID>OKGo1234</MerchantID>
<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.
54
Chapter 4
Transfer Refunds
Important
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
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)
Data Type
& Length
bankInfo_bankCode
Code for the customer’s bank.
Real-Time Bank
Transfer (O)
String (8)
bankInfo_country
Country in which the bank is located. Use the
two-character ISO Standard Country Codes.
Real-Time Bank
Transfer (R)
String (2)
bankTransferRealTime
Service_bankTransfer
RealTimeType
Code that indicates which payment method or
bank to use for this transaction. See Table 13,
page 60.
Real-Time Bank
Transfer (R)
String (2)
bankTransferRealTime
Service_run
Set to true to include the real-time bank
transfer service in your request.
Real-Time Bank
Transfer (R)
String (5)
billTo_city
Real-Time Bank
Transfer (R)
String (50)
billTo_company
Real-Time Bank
Transfer (O)
String (60)
55
Chapter 4
Table 12
Request Fields for Real-Time Bank Transfers Using the Simple Order API (Continued)
Request Field
Description
Required (R) or
Optional (O)
Data Type
& Length
billTo_country
Real-Time Bank
Transfer (R)
String (2)
billTo_email
Customer’s email address, including the full
domain name. For example:
[email protected]
Real-Time Bank
Transfer (R)
String (255)
billTo_firstName
Real-Time Bank
Transfer (R)
String (60)
billTo_language
Language used for the order. Use the ISO
standard language codes.
Real-Time Bank
Transfer (O)
String (2)
billTo_lastName
Real-Time Bank
Transfer (R)
String (60)
billTo_phoneNumber
Real-Time Bank
Transfer (O)
String (15)
billTo_postalCode
Postal code for the billing address. The postal
code must consist of 5 to 9 digits.
Real-Time Bank
Transfer (R if
billing country is
US or CA)
String (10)
If the value of billTo_country is US, the 9-digit
postal code must follow this format:
Example: 12345-6789
If the value of billTo_country is CA, the 6-digit
postal code must follow this format:
Example: A1B 2C3
billTo_state
Billing address state. This field is required if the
billTo_country value is US or CA.
Real-Time Bank
Transfer (See
description)
String (2)
billTo_street1
Billing address street address.
Real-Time Bank
Transfer (R)
String (60)
billTo_street2
Additional address information.
Real-Time Bank
Transfer (O)
String (60)
fundTransfer_
accountNumber
Customer’s bank account number.
Real-Time Bank
Transfer (O)
String (10)
fundTransfer_iban
International Bank Account Number (IBAN) for
the bank account.
Real-Time Bank
Transfer (See
description)
String (30)
country-specific.
56
Chapter 4
Table 12
Request Field
Description
Required (R) or
Optional (O)
Data Type
& Length
invoiceHeader_
merchantDescriptor
Merchant descriptor that is displayed on the
customer’s statement for each real-time bank
transfer.
Real-Time Bank
Transfer (O)
String (50)
Real-Time Bank
Transfer (O)
String (30)
For iDEAL:
String (32)
To enable this field and to optionally set a
default descriptor for all real-time bank
transfers, contact CyberSource Customer
Support.
item_#_productCode
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.
item_#_productName
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.
Real-Time Bank
Transfer (See
description)
String (30)
item_#_productSKU
Product identifier code. It is required if item_#_
productCode is not default, stored_
and/or handling.
Real-Time Bank
Transfer (See
description)
String (30)
item_#_quantity
Quantity of the product being purchased. The
default value is 1. This field is required if item_
#_productCode is not default, stored_
and/or handling.
Real-Time Bank
Transfer (See
description)
Integer (10)
57
Chapter 4
Table 12
Request Field
Description
Required (R) or
Optional (O)
Data Type
& Length
item_#_taxAmount
Tax amount associated with this item. This field
is additive. For example, if you send these offer
lines:
Real-Time Bank
Transfer (O)
String (15)
Real-Time Bank
Transfer (See
description)
String (15)
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
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.
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
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)
String (26)
merchantID
Real-Time Bank
Transfer (R)
String (30)
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 (50)
58
Chapter 4
Table 12
Request Field
Description
Required (R) or
Optional (O)
Data Type
& Length
Real-Time Bank
Transfer (R)
String (5)
purchaseTotals_
grandTotalAmount
either this field or item_#_unitPrice in your
request. For more information about items and
grand totals, see Getting Started with
API.
Real-Time Bank
Transfer (See
description)
String (15)
returnURL
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:
Real-Time Bank
Transfer (See
description)
String (512)

Send this field with every request.

Provide the URL when you register for the
service, and CyberSource will store it in a
database.
shipTo_city
City of shipping address. This field is required if
any shipping information is included in the
request.
Real-Time Bank
Transfer (See
description)
String (50)
shipTo_country
Country of shipping address. Use the twocharacter ISO Standard Country Codes.
Real-Time Bank
Transfer (O)
String (2)
shipTo_firstName
First name of the person receiving the product.
Real-Time Bank
Transfer (O)
String (60)
shipTo_lastName
Last name of the person receiving the product.
Real-Time Bank
Transfer (O)
String (60)
shipTo_phoneNumber
Real-Time Bank
Transfer (O)
String (15)
shipTo_postalCode
Postal code for the shipping address. The postal
Real-Time Bank
Transfer (R if
shipTo_country is
US or CA)
String (10)
If the value of shipTo_country is US, the 9-digit
postal code must follow these rules:
Example: 12345-6789
If the value of shipTo_country is CA, the 6-digit
postal code must follow these rules:
Example: A1B 2C4
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.
59
Chapter 4
Table 12
Request Field
Description
Required (R) or
Optional (O)
Data Type
& Length
shipTo_state
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.
Real-Time Bank
Transfer (See
description)
String (2)
shipTo_street1
First line of shipping address. This field is
required if any shipping information is included
in the request.
Real-Time Bank
Transfer (See
description)
String (60)
shipTo_street2
Second line of shipping address.
Real-Time Bank
Transfer (O)
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
specific bank on a web page that you do not
control.
11
eCard
Poland
control.
12
eNets
Singapore
control.
17
Akita
Finland
control.
18
Sofortuberweisung
Germany
control.
60
Chapter 4
Table 13
Bank Transfer Real Time Type (Continued)
Bank
Code
Bank or
Payment Type
Country
Bank or Network
20
Poli
Australia
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)
formAction
URL that will be used to re-direct the customer’s browser
window back to your web site.
String (4000)
formMethod
Method that redirects the customer’s browser window to
your web site. The possible values are:
String (4)

GET

POST
paymentReference
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.
String (16)
reasonCode
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.
Integer (5)
reconciliationID
information about tracking orders in Getting Started with
CyberSource Advanced for the Simple Order API.
String (60)
requestDateTime
Time the real-time bank transfer was requested.
Example: 2007-08-11T22: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.
String (20)
bankTransferRefundReply_iban
International Bank Account Number (IBAN) for the bank
account.
Alphanumeric
(50)
61
Chapter 4
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:
String (6)
invalidField_0...N

ACCEPT

ERROR

REJECT
Fields in the request that contained invalid data. These reply
fields are included as an aid to software developers only.
String (100)
Note Do not attempt to use these fields for interacting with
end users.
For more information about missing and invalid fields, see
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.
String (50)
missingField_0...N
Required fields that were missing from the request. These
reply fields are included as an aid to software developers
only.
String (100)
Note Do not attempt to use these fields for interacting with
end users.
For more information about missing and invalid fields, see
Order API.
Currency used for the order. Use the ISO Standard Currency
Codes.
String (5)
reasonCode
Numeric value corresponding to the result of the overall
request. See "Reason Codes," page 155, for a list of
possible values.
Integer (5)
requestID
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)
62
Chapter 4
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
Request Field
Description
Required (R) or
Optional (O)
Data
Type &
Length
bankTransferRefund
RealTimeReconciliationID
Global Collect.
Bank Transfer
Refund (R for
standalone
refunds)
String (60)
Bank Transfer
Refund (R)
String (26)
bankTransferRefund
RealTimeRequestID
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
bankTransferRequestID field.
63
Chapter 4
Real-Time Bank Transfer Request
Example 16
<bankTransferRealTimeService run="true"/>
<merchantID>demo</merchantID>
<merchantReferenceCode>482046</merchantReferenceCode>
<billTo>
<firstName>John</firstName>
<street1>Boschdijk 987</street1>
<city>Eindhoven</city>
<language>nl</language>
<postalCode>5600 PB</postalCode>
<phoneNumber>040-5551212</phoneNumber>
</billTo>
<purchaseTotals>
</purchaseTotals>
<item id="0">
<unitPrice>49.95</unitPrice>
<quantity>1</quantity>
</item>
<bankTransferRealTimeService>
<bankTransferRealTimeType>7</bankTransferRealTimeType>
</bankTransferRealTimeService>
<bankInfo>
</bankInfo>
</requestMessage>
64
Chapter 4
Real-Time Bank Transfer Reply
Example 17
<c:merchantReferenceCode>482046</c:merchantReferenceCode>
<c:purchaseTotals>
<c:currency>EUR</c:currency>
</c:purchaseTotals>
<c:bankTransferRealTimeReply>
<c:formMethod>GET</c:formMethod>
<c:formAction>http://www.cybs.com?REF=124&MAC=346o+123</c:formAction>
</c:bankTransferRealTimeReply>
</c:replyMessage>
Real-Time Bank Transfer Refund
Example 18
Real-Time Bank Transfer Refund Request
<billTo>
</billTo>
<purchaseTotals>
</purchaseTotals>
<fundTransfer>
</fundTransfer>
65
Chapter 4
<bankInfo>
</bankInfo>
<bankTransferRefundService run="true">
</bankTransferRefundService>
</requestMessage>
Example 19
<c:purchaseTotals>
</c:purchaseTotals>
<c:bankTransferRefundReply>
<c:iban>DE58790500000044497071</c:iban>
</c:bankTransferRefundReply>
</c:replyMessage>
66
CHAPTER
Real-Time Bank Transfers
Using the SCMP API
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.
For China, real-time bank transfer settlements are not posted until the next
business day.
Note
Sending the Query
To send the query, send the fields described in the following table in an HTTP POST
request to the following URL:
https://ebc.cybersource.com/ebc/Query
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
R
String (30)
Type of query. The only possible value is
R
String (30)
type
transaction.
subtype
Query subtype. The only possible value is
transactionStatus.
R
String (30)
requestID
Request ID returned in the real-time bank
transfer reply.
R
String (26)
transRefNo
Transaction reference number (SCMP API)
or reconciliation ID (Simple Order API)
returned in the real-time bank transfer reply.
R
String (60)
67
Chapter 5
Table 16
Required Data for the On-Demand Transaction Status Query (Continued)
Field
Description
Required (R)
or Optional (O)
Data Type
& Length
requestToken
Request token data generated by
CyberSource for each transaction reply.
R
String (256)
This example shows an on-demand query for a transaction’s status:
Example 20
On-Demand Transaction Status Query
<html>
<body>
<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>
68
Chapter 5
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
<!ELEMENT
<!ELEMENT
<!ELEMENT
<!ELEMENT
<!ELEMENT
<!ELEMENT
<!ELEMENT
xml (Request, Response)>
Request (MerchantID, RequestID)>
MerchantID (#PCDATA)>
RequestID (#PCDATA)>
Response (PaymentStatus?)>
PaymentStatus (Status, ProcessorMessage?)>
Status (#PCDATA)>
ProcessorMessage (#PCDATA)>
This example shows on-demand query results for a successful real-time bank transfer
payment:
Example 21
Successful Payment
<xml>
<Request>
<Response>
<PaymentStatus>
<Status>Payment</Status>
</PaymentStatus>
</Response>
</Request>
</xml>
69
Chapter 5
This example shows on-demand query results for a failed real-time bank transfer
payment:
Example 22
Failed Payment
<xml>
<Request>
<Response>
<PaymentStatus>
<Status>Failed</Status>
<ProcessorMessage>Payment instruction has been rejected</ProcessorMessage>
</PaymentStatus>
</Response>
</Request>
</xml>
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.
70
Chapter 5
Transfer Refunds
Important
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
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)
Data
Type &
Length
bank_account_number
Customer’s bank account number.
Real-Time Bank
Transfer (O)
String (10)
bank_code
Code for the customer’s bank.
Real-Time Bank
Transfer (O)
String (8)
bank_country
Country where the bank is located. Use the
two-character ISO Standard Country Codes.
Real-Time Bank
Transfer (R)
String (2)
bank_iban
International Bank Account Number (IBAN) for
the bank account.
Real-Time Bank
Transfer (See
description)
String (30)
country-specific requirements.
71
Chapter 5
Table 17
Request-Level Fields for Real-Time Bank Transfers Using the SCMP API (Continued)
Request-Level Field
Description
Required (R) or
Optional (O)
Data
Type &
Length
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)
String (2)
bill_address1
Real-Time Bank
Transfer (R)
String (60)
bill_address2
Real-Time Bank
Transfer (O)
String (60)
bill_city
Real-Time Bank
Transfer (R)
String (50)
bill_country
Real-Time Bank
Transfer (R)
String (2)
bill_state
Billing address state. This field is required if the
value of bill_country is US or CA.
Real-Time Bank
Transfer (See
description)
String (2)
bill_zip
Zip code for the shipping address. The zip
Real-Time Bank
Transfer (R if bill_
country is US or
CA)
String (10)
If the value of bill_country is US, the 9-digit
Example:12345-6789
If the value of bill_country is CA, the 6-digit
Example: A1B 2C3
company_name
Real-Time Bank
Transfer (O)
String (60)
currency
Real-Time Bank
Transfer (R)
String (5)
customer_email
Customer’s email address. For example:
[email protected]
Real-Time Bank
Transfer (R)
String
(255)
customer_firstname
Real-Time Bank
Transfer (R)
String (60)
customer_language
Language used for the order. Use the ISO
standard language codes.
Real-Time Bank
Transfer (O)
String (2)
customer_lastname
Real-Time Bank
Transfer (R)
String (60)
customer_phone
Real-Time Bank
Transfer (O)
String (15)
72
Chapter 5
Table 17
Request-Level Field
Description
Required (R) or
Optional (O)
Data
Type &
Length
grand_total_amount
either this field or offer0 and the offer-level
field amount. See the information about offers
and grand totals in Getting Started with
Real-Time Bank
Transfer (See
description)
Decimal
(15)
ics_applications
Real-Time Bank
Transfer (R)
String
(255)
link_to_request
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.
Real-Time Bank
Transfer (O)
String (26)
merchant_descriptor
Merchant descriptor that is displayed on the
customer’s statement for each real-time bank
transfer.
Real-Time Bank
Transfer (O)
String (50)
For iDEAL:
String (32)
To enable this field and to optionally set a
default descriptor for all real-time bank
transfers, contact CyberSource Customer
Support.
merchant_id
Real-Time Bank
Transfer (R)
String (30)
merchant_ref_number
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
SCMP API.
Real-Time Bank
Transfer (R)
String (50)
offer0...N
Offers for the request. An offer is a line item for
the order.
Real-Time Bank
Transfer (O)
String (50)
return_url
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:
Real-Time Bank
Transfer (See
description)
String
(512)
Real-Time Bank
Transfer (See
description)
String (60)
ship_to_address1

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.
73
Chapter 5
Table 17
Request-Level Field
Description
Required (R) or
Optional (O)
Data
Type &
Length
ship_to_address2
Second line of the address to which the
product will be shipped.
Real-Time Bank
Transfer (O)
String (60)
ship_to_city
City to which the product will be shipped. This
field is required if any shipping information is
included in the request.
Real-Time Bank
Transfer (See
description)
String (50)
ship_to_country
Country to which the product will be shipped.
Use the two-character ISO Standard Country
Codes.
Real-Time Bank
Transfer (O)
String (2)
ship_to_firstname
Real-Time Bank
Transfer (O)
String (60)
ship_to_lastname
Real-Time Bank
Transfer (O)
String (60)
ship_to_phone
Real-Time Bank
Transfer (O)
String (15)
ship_to_state
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.
Real-Time Bank
Transfer (See
description)
String (2)
ship_to_zip
Real-Time Bank
Transfer (R is if
ship_to_country
is US or CA)
String (10)
Real-Time Bank
Transfer (O)
Positive
integer (3)
If the value of ship_to_country is US, the 9digit zip code must follow this format:
Example: 12345-6789
If the value of ship_to_country is CA, the 6digit zip code must follow this format:
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.
timeout
Number of seconds until the transaction times
out. The default is 110 seconds.
74
Chapter 5
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)
Data
Type &
Length
amount
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
Real-Time Bank
Transfer (See
description)
Decimal
(15)
truncated at the request level to the correct
number of decimal places.
merchant_product_sku
Product identifier code. It is required if
product_code is not default, stored_
value, or one of the values related to
Real-Time Bank
Transfer (See
description)
String (30)
product_code
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.
Real-Time Bank
Transfer (O)
String (30)
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. This field is required if
value or one of the values related to
Real-Time Bank
Transfer (See
description)
String (30)
quantity
The default value is 1. This field is required if
value or one of the values related to
Real-Time Bank
Transfer (See
description)
Nonnegative
integer (10)
75
Chapter 5
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)
the total amount authorized will be for 32.40,
not 30.00 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
9
GiroPay
Germany
control.
11
eCard
Poland
control.
12
eNets
Singapore
control.
76
Chapter 5
Table 19
Bank Transfer Real-Time Type (Continued)
Bank
Code
Bank or
Payment Type
Country
Bank or Network
17
Akita
Finland
control.
18
Sofortuberweisung
Germany
control.
20
Poli
Australia
control.
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
77
Chapter 5
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
account.
Alphanumeric
(50)
bank_transfer_real_time_amount
Total amount for the real-time bank transfer.
Decimal (15)
bank_transfer_real_time_form_
action
URL that will be used to re-direct the customer’s browser
window back to your web site.
String (4000)
bank_transfer_real_time_form_
method
Method that will be used to re-direct the customer’s browser
window back to your web site. The possible values are:
String (4)

GET

POST
payment_reference
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.
String (16)
bank_transfer_real_time_rcode
One-digit code that indicates whether the ics_bank_
transfer_real_time request was successful.
Integer (1)
bank_transfer_real_time_rflag
transfer_real_time request.
String (50)
bank_transfer_real_time_rmsg
Message that explains the reply flag bank_transfer_real_
time_rflag.
String (255)
bank_transfer_real_time_time
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.
Date and time
(20)
bank_transfer_real_time_trans_
ref_no
information about tracking orders in Getting Started with
String (60)
client_lib_version
Information about the client library used to request the
transaction.
String (50)
currency
Currency used for the order. Use the ISO Standard
Currency Codes.
String (5)
ics_rcode
One-digit code that indicates whether the entire request was
successful. The possible values are:
Integer (1)
ics_rflag



One-word description of the result of the entire request.
String (50)
78
Chapter 5
Table 20
Reply Fields for Real-Time Bank Transfers Using the SCMP API (Continued)
Reply Field
Description
Data Type &
Length
ics_rmsg
String (255)
merchant_ref_number
request. If you included multi-byte characters in this field in
the request, the returned value might contain corrupted
characters.
String (50)
request_id
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
Description
DINVALIDDATA
DMISSINGFIELD
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.
ETIMEOUT
SOK
79
Chapter 5
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)
Data Type
& Length
request_id
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.
Bank Transfer
Refund (R)
String (26)
trans_ref_no
Global Collect.
Bank Transfer
Refund (R for
standalone
refunds)
String (60)
refund request, CyberSource will generate
the value.
80
Chapter 5
Example 23
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
[email protected]
customer_firstname =john
customer_lastname=smith
customer_language=nl
grand_total_amount=10.00
merchant_id=demo
merchant_ref_number=C299792458C
Example 24
request_id=0305782650000167905080
currency=EUR
ics_rcode=1
ics_rflag=SOK
bank_transfer_real_time_trans_ref_no=0308014624
bank_transfer_real_time_amount=10.00
bank_transfer_real_time_time=2012-01-22T170910Z
bank_transfer_real_time_payment_reference=106157214759
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
81
Chapter 5
Example 25
bank_check_digit=12
bank_city=Paris
bank_country=France
bank_transfer_real_time_request_id=4024360119000179087451
bill_country=FR
bill_zip=06513
currency=EUR
[email protected]
merchant_id=demo
ship_to_country=US
ship_to_zip=47404
82
Chapter 5
Example 26
bank_transfer_refund_amount=1.81
bank_transfer_refund_iban=IE64BOFI30004 00819 00010023116 61
bank_transfer_refund_rcode=1
bank_transfer_refund_rflag=SOK
bank_transfer_refund_rmsg=Request was processed successfully.
bank_transfer_refund_time=2014-06-10T213332Z
bank_transfer_refund_trans_ref_no=2149563030
currency=eur
ics_rcode=1
ics_rflag=SOK
request_id=4024360120420179087451
83
CHAPTER
Boletos Bancários Using the
Simple Order API
6
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
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 as @
and #.
84
Chapter 6
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
Required
String (60)
billTo_lastName
Required
String (60)
billTo_personalID
Personal identifier. For CyberSource Latin
American Processing, you can use this field
for the Cadastro de Pessoas Fisicas (CPF).
Optional
String (18)
boletoPaymentService_
expirationDate
Expiration date of the Boleto Bancário in
GMT in ISO format: YYYY-MM-DD.
Optional
String (10)
boletoPaymentService_
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 form. The customer
message field is often used to remind the
customer to submit the Boleto promptly.
Optional
String (512)
boletoPaymentService_run
Whether to include boletoPaymentService
in your request. Possible values:
Required
String (50)
Optional
Decimal
(15)
Optional
String (26)
item_#_unitPrice

true: Include the service in your request.

false (default): Do not include the service
in your request.
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.
linkToRequest
when using multiple payment methods to
complete an order. For more information
about partial authorizations, see Credit
Card Services Using the Simple Order API.
85
Chapter 6
Table 23
Request Fields for Boletos Bancários for the Simple Order API (Continued)
Request Field
Description
Required or
Optional
Data Type
& Length
merchantID
Required
String (30)
CyberSource, be sure to inform
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.
tracking number. For more information, see
Required
String (50)
purchaseTotals_
grandTotalAmount
either this field or item_#_unitPrice in your
request. For more information, see Getting
Simple Order API.
Required
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
Total amount of the Boleto Bancário payment.
Decimal
(15)
boletoPaymentReply_
boletoNumber
Boleto Bancário payment number.
String (6)
boletoPaymentReply_
expirationDate
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.
String (20)
Note There is a space between the date and the time.
boletoPaymentReply_
reasonCode
Numeric value corresponding to the result of the Boleto Bancário
request. See Appendix B, "Reason Codes," on page 155.
Integer (5)
boletoPaymentReply_
reconciliationID
Unique value generated by CyberSource. For more information
about tracking orders, see Getting Started with CyberSource
String (60)
86
Chapter 6
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.
Example: 2007-08-11T22: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
Summarizes the result of the overall request. Possible values:
String (6)

ACCEPT

ERROR

REJECT
For more information about decision values, see Getting Started
with CyberSource Advanced for the Simple Order API.
invalidField_0…N
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
String (100)
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
String (50)
missingField_0...N
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 (100)
Currency used for the order. The only possible value is BRL.
String (5)
reasonCode
Numeric value corresponding to the result of the overall request.
See Appendix B, "Reason Codes," on page 155.
Integer (5)
requestID
Identifier for the request. For more information about request
tokens, see Getting Started with CyberSource Advanced for the
Simple Order API.
String (26)
87
Chapter 6
Examples
Name-Value Pairs: Request
Example 27
Boleto Bancário Request
billTo_firstName=Jane
billTo_lastName=Smith
billTo_personalID=1111
merchantID=okgo
merchantReferenceCode=1234567
item_0_unitPrice=10.00
boletoPaymentService_run=true
boletoPaymentService_instruction=this is a test
boletoPaymentService_expirationDate=2008-11-22
Name-Value Pairs: Reply
Example 28
Boleto Bancário Reply
decision=ACCEPT
reasonCode=100
requestID=12345678901234567890
merchantReferenceCode=1234567
purchaseTotals_currency=BRL
boletoPaymentReply_reasonCode=100
boletoPaymentReply_reconciliationID=12345678
boletoPaymentReply_amount=10.00
boletoPaymentReply_boletoNumber=123456
boletoPaymentReply_expirationDate=2008-11-22 23:59:59
boletoPaymentReply_url=https://www.pagador.com.br/pagador/
reenvia.asp?Id_Transacao=93b5668a-6129-48d5-ad95-76308d997479
88
Chapter 6
XML: Request
Example 29
<billTo>
<firstName>Jane</firstName>
<personalID>1111</personalID>
</billTo>
<merchantID>okgo</merchantID>
<merchantReferenceCode>1234567</merchantReferenceCode>
<item id="0"><unitPrice>10.00</unitPrice></item>
<boletoPaymentService run="true">
<instruction>this is a test</instruction>
<expirationDate>2008-11-22</expirationDate>
</boletoPaymentService>
</requestMessage>
XML: Reply
Example 30
<c:merchantReferenceCode>1234567</c:merchantReferenceCode>
<c:purchaseTotals><c:currency>BRL</c:currency></c:purchaseTotals>
<c:boletoPaymentReply>
<c:boletoNumber>123456</c:boletoNumber>
<c:expirationDate>2008-11-22 23:59:59</c:expirationDate>
<c:url>https://www.pagador.com.br/pagador/reenvia.asp?
Id_Transacao=93b5668a-6129-48d5-ad95-76308d997479</c:url>
</c:boletoPaymentReply>
</c:replyMessage>
89
CHAPTER
7
Boletos Bancários Using the
SCMP API
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
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
Description
Required or
Optional
Data Type
& Length
boleto_payment_
expiration_date
Expiration date of the Boleto Bancário in GMT in
ISO format: YYYY-MM-DD.
Optional
String (10)
90
Chapter 7
Table 25
Request-Level Fields for Boletos Bancários for the SCMP API (Continued)
Request-Level
Field
Description
Required or
Optional
Data Type
& Length
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
Required
String (60)
customer_lastname
Required
String (60)
grand_total_amount
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.
Required
Decimal
(15)
ics_applications
Service to process for the request. For a Boleto
Bancário request, this value must be ics_boleto_
payment.
Required
String (255)
link_to_request
payment methods to complete an order. For more
information about partial authorizations, see Credit
Card Services Using the SCMP API.
Optional
String (26)
merchant_id
Required
String (30)
Required
String (50)
CyberSource, make sure that you inform
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_ref_
number
number. For more information about tracking
orders, see Getting Started with CyberSource
91
Chapter 7
Table 25
Request-Level Fields for Boletos Bancários for the SCMP API (Continued)
Request-Level
Field
Description
Required or
Optional
Data Type
& Length
offerN: amount
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
Optional
Decimal
(15)
Optional
String (18)
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_id
Personal identifier. For CyberSource Latin
American Processing, you can use this field for the
Cadastro de Pessoas Fisicas (CPF).
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
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.
String (20)
Note There is a space between the date and the time.
boleto_payment_rcode
One-digit code that indicates whether the ics_boleto_payment
request was successful:



Integer (1)
For more information about handling replies, see Getting Started
boleto_payment_request_
time
Time of the Boleto Bancário request in UTC. For more information
about the format, see the data type information in Getting Started
Date and
time (20)
92
Chapter 7
Table 26
Reply Fields for Boletos Bancários for the SCMP API (Continued)
Reply Field
Description
Data Type
& Length
boleto_payment_rflag
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.
String (50)
boleto_payment_rmsg
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
String (255)
boleto_payment_trans_ref_
no
Unique value generated by CyberSource. For more information,
see Getting Started with CyberSource Advanced for the SCMP API.
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:
Integer (1)



For more information, see Getting Started with CyberSource
ics_rflag
One-word description of the result of the entire request. See "Reply
Flags," page 94, and for more information, see Getting Started with
String (50)
ics_rmsg
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
String (255)
merchant_ref_number
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
String (50)
request_id
Unique identifier generated by CyberSource for the transaction. For
more information about request IDs, see Getting Started with
String (26)
93
Chapter 7
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
Description
DBOLETODECLINED
When CyberSource sent a Boleto Bancário request to CyberSource
Latin American Processing, the processor returned an error to
CyberSource.
DINVALIDDATA
DMISSINGFIELD
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 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.
ETIMEOUT
SOK
94
Chapter 7
Request
Example 31
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=1234567
sku:testdl^quantity:1âmount:1.18^tax_amount:0.00^product_name:Clorox
Wipesôffer_id:0
boleto_payment_instruction=my test
boleto_payment_expiration_date=2008-11-22
personal_id=1111
Reply
Example 32
boleto_payment_url=https://www.pagador.com.br/pagador/reenvia.asp?Id_
Transacao=93b5668a-6129-48d5-ad95-76308d997479
ics_rcode=1
request_id=2259925521130170394179
boleto_payment_rcode=1
boleto_payment_boleto_number=100000
boleto_payment_rmsg=Request was processed successfully.
boleto_payment_trans_ref_no=10992551
ics_rflag=SOK
boleto_payment_rflag=SOK
merchant_ref_number=1654291
boleto_payment_expiration_date=2008-11-22 23:59:59
95
CHAPTER
Reports for Boletos
Bancários
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”.
96
Chapter 8
To view and download reports:
Step 1
Navigate to the Boleto Bancário Unfulfilled Report.
Step 2
Click I need help with this page.
A help topic for the Boleto Bancário Unfulfilled Report opens.
Step 3
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.
97
Chapter 8
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
Description
<Sample>
Parent of the subsequent elements.
Attribute=CDATA
Name of the attribute followed by the XML data format for
the attribute.
(Element)
Required element. Must appear only once.
(ChoiceOne) | (ChoiceTwo)
Element <ChoiceOne> or <ChoiceTwo> but not both.
(ComplexElement)
Element with one or more children.
(RequiredRecurringElement)+
Required element. Can appear one or more times.
(OptionalElement)?
Optional element. Can appear once or be omitted.
(OptionalRecurringElement)*
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 as @, #, and %.
All text uses UTF-8 character encoding.
Boolean
Single character: T for true or F for false.
Amount
Can include a decimal point.
Date
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.
98
Chapter 8
Table 29
Data Types for XML Reports (Continued)
Data Type
Description
DateTime
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>
99
Chapter 8
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 https://ebc.cybersource.com/
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
Description
<Summary>
Summary of the transaction information for each range. See
"<Summary>," page 101.
<TransactionDetail>
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=https://ebc.cybersource.com/ebc/reports/dtd/bbur.dtd
MerchantID="exampleMerchant"
ReportDate="2008-01-24T08:00:00-08:00">
<Summary>
...
</Summary>
<TransactionDetail>
...
</TransactionDetail>
</Report>
100
Chapter 8
<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






Syntax
<Summary>
(Range)*
</Summary>
Child Element
Table 32
Child Element of <Summary> in the Boleto Bancário Unfulfilled Report
Element Name
Description
<Range>
Summary of the transaction information for one range. See
"<Range>," page 103.
Example
Example 34
<Summary> Element
<Summary>
<Range DaysOutstandingStart="3"
<Count>0</Count>
<NetAmount>0.00</NetAmount>
</Range>
<Count>0</Count>
</Range>
<Count>0</Count>
</Range>
<Count>0</Count>
</Range>
DaysOutstandingEnd="3" CurrencyCode="BRL">
DaysOutstandingEnd="3" CurrencyCode="USD">
DaysOutstandingEnd="4" CurrencyCode="BRL">
DaysOutstandingEnd="4" CurrencyCode="USD">
101
Chapter 8
Example 34
<Summary> Element (Continued)
<Range DaysOutstandingStart="5" DaysOutstandingEnd=" 7" CurrencyCode="BRL">
<Count>2</Count>
</Range>
<Range DaysOutstandingStart="5" DaysOutstandingEnd=" 7" CurrencyCode="USD">
<Count>0</Count>
</Range>
<Range DaysOutstandingStart="8" DaysOutstandingEnd="14" CurrencyCode="BRL">
<Count>8</Count>
</Range>
<Range DaysOutstandingStart="8" DaysOutstandingEnd="14" CurrencyCode="USD">
<Count>0</Count>
</Range>
<Count>21</Count>
</Range>
<Count>0</Count>
</Range>
<Count>7</Count>
</Range>
<Count>0</Count>
</Range>
<Count>0</Count>
</Range>
<Count>0</Count>
</Range>
<Range DaysOutstandingStart="91 DaysOutstandingEnd="180" CurrencyCode="BRL">
<Count>0</Count>
</Range>
<Range DaysOutstandingStart="91 DaysOutstandingEnd="180" CurrencyCode="USD">
<Count>0</Count>
</Range>
102
Chapter 8
Example 34
<Summary> Element (Continued)
<Count>38</Count>
</Range>
<Count>0</Count>
</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
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.
Alphanumeric (4)
DaysOutstandingEnd
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.
Alphanumeric (4)
CurrencyCode
Currency code. Possible value:
Alphanumeric (5)

BRL
103
Chapter 8
Child Elements
Table 34
Child Elements of <Range> in the Boleto Bancário Unfulfilled Report
Element Name
Description
Count
Number of transactions that await funding in the currency specified
by CurrencyCode and in the range specified by
DaysOutstandingStart and DaysOutstandingEnd.
NetAmount
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>
</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)*
Child Elements
Table 35
Child Element of <TransactionDetail> in the Boleto Bancário
Unfulfilled Report
Element Name
Description
<Transaction>
Information about an unfunded transaction. See "<Transaction>,"
page 105.
104
Chapter 8
Example
Example 36
<TransactionDetail> Element
<TransactionDetail>
<Transaction>
...
</Transaction>
<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
Payment processor used for the
transaction. This value is always
Alphanumeric (40)
brazilboleto: braspag.
DaysOutstanding
Number of days since the transaction was
initiated.
Alphanumeric (4)
MerchantID
CyberSource merchant ID.
Alphanumeric (30)
OriginalTransactionDate
Date that the original payment transaction
was initiated.
DateTime (25)
RequestID
Unique identifier generated by
CyberSource for the transaction. For more
information about request IDs, see Getting
Simple Order API or Getting Started with
Numeric (26)
105
Chapter 8
Table 36
Unfulfilled Report (Continued)
Attribute Name
Description
Data Type &
Length
TransactionReference
Number
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:
Alphanumeric (60)

<service>_reconciliationID for the
Simple Order API.

<service>_trans_ref_no for the SCMP
API.
For more information about tracking orders,
Advanced for the Simple Order API or
MerchantReference
Number
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.
Alphanumeric (50)
See the information about tracking orders,
Advanced for the Simple Order API or
Amount
Amount of the transaction. For refunds, the
amount is negative.
Amount (19)
CurrencyCode
Currency code used for the transaction.
Possible value:
Alphanumeric (5)

BRL
106
Chapter 8
Table 36
Unfulfilled Report (Continued)
Attribute Name
Description
Data Type &
Length
EventType
Type of event that occurred for the
transaction. Possible values:
Alphanumeric (20)
BoletoNumber

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 (15)
Example
Example 37
<Transaction> Element
<Transaction Processor="brazilboleto"
DaysOutstanding="3"
MerchantID="123456789"
OriginalTransactionDate="2009-01-11T10:45:00-08:00"
RequestID="912342343468"
TransactionReferenceNumber="123456"
MerchantReferenceNumber="2884554"
Amount="75,00"
CurrencyCode="BRL"
EventType="Fulfilled"
BoletoNumber="987654">
</Transaction>
107
Chapter 8
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>
108
Chapter 8
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, 3-180 days outstanding
These transactions are included in the following ranges in the <Summary> section:

3 days outstanding


Example 38
Unfulfilled Transactions
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE Report SYSTEM "https://ebctest.cybersource.com/ebctest/reports/
dtd/bbur.dtd">
<Report Name="BoletoBancarioUnfulfilledReport"
Version="1.0"
xmlns="https://ebctest.cybersource.com/ebctest/reports/dtd/bbur.dtd"
MerchantID="examplemerchant"
ReportDate="2008-01-24T08:00:00-08:00">
<Summary>
DaysOutstandingEnd="3"
CurrencyCode="BRL">
<Count>1</Count>
</Range>
CurrencyCode="BRL">
<Count>0</Count>
</Range>
CurrencyCode="BRL">
<Count>5</Count>
</Range>
CurrencyCode="BRL">
<Count>6</Count>
109
Chapter 8
</Range>
</Summary>
<TransactionDetail>
DaysOutstanding="3"
RequestID="2009608779023232235878"
TransactionReferenceNumber="20080122_1684_608779023232235878"
Amount="1.20"
CurrencyCode="BRL"
EventType="Pending Fulfillment"
BoletoNumber="321654851"/>
DaysOutstanding="5"
RequestID="2007967037043232235878"
Amount="1.20"
CurrencyCode="BRL"
DaysOutstanding="5"
RequestID="2007967037043232235878"
Amount="1.20"
CurrencyCode="BRL"
DaysOutstanding="6"
RequestID="2007967037043232235878"
Amount="1.20"
CurrencyCode="BRL"
DaysOutstanding="7"
RequestID="2007967037043232235878"
110
Chapter 8
Amount="1.20"
CurrencyCode="BRL"
DaysOutstanding="7"
RequestID="2007967037043232235878"
Amount="1.20"
CurrencyCode="BRL"
</Report>
111
Chapter 8
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
<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="1999370597170167905049"></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>
112
Chapter 8
Example 40
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE Report (View Source for full doctype...)>
<Report xmlns="https://ebctest.cybersource.com/ebctest/reports/dtd/tdr_1_4.dtd"
Name="Transaction Detail"
Version="1.4"
MerchantID="nwtest1"
ReportStartDate="2008-01-09T19:50:59-08:00"
ReportEndDate="2008-01-09T19:50:59-08:00">
<Requests>
<Request MerchantReferenceNumber="1234567890"
RequestDate="2008-09-10T14:00:08-08:00"
RequestID="1999370597170167905049"
SubscriptionID=""
Source="SCMP API"
TransactionReferenceNumber="0001094522"
PredecessorRequestID=”7904567221330010160804”>
<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>
<Email />
<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>
113
Chapter 8
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>
114
CHAPTER
Direct Debits and Direct
Debit Refunds Using the
Simple Order API
Important
9
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.
Important
Note
BBAN it will be converted to an IBAN; this conversion process will continue only
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
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.
115
Chapter 9
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
refund again with the correct number.
Important
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.

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,
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.

for merchantReferenceCode that you used for the direct debit. This makes it easier
116
Chapter 9
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
You will not receive an error in the reply for any of the following conditions:

The directDebitRefundService_requestID field is invalid.

Instead, CyberSource will not process the refund and the transaction will appear in the
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.
117
Chapter 9
API Fields
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
Request Field
Description
Required (R)
or Optional
(O)
Data Type &
Length
bankInfo_address
Bank’s address.
Direct Debit (O)
String (255)
Refund (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
information.
Direct Debit (See
description)
Code that identifies the branch of the
customer's bank when you are not using
Direct Debit (See
description)
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.
Direct Debit (See
description)
Possible values are the two-character ISO
Standard Country Codes.
Direct Debit (R)
Bank's name. Required when using the
Global Collect processor to make one of
the following types of direct debit
transactions:
Direct Debit (See
description)

Direct debit

Stand-alone direct debit refund
String (See
description)
Refund (See
description)
String (15)
Refund (See
description)
String (35)
Refund (See
description)
String (2)
Refund (R)
String (40)
Refund (See
description)
Otherwise it is optional.
118
Chapter 9
Table 37
Request Field
Description
Required (R)
or Optional
(O)
Data Type &
Length
bankInfo_swiftCode
Bank’s SWIFT code. Unique address of the
bank. Also known as the Bank
Identification Code (BIC).
Direct Debit (O)
String (30)
Refund (O)
Note This field is optional; however,
CyberSource strongly recommends
including this code in each request when
the IBAN is included in the request.
billTo_city
City for the billing address.
Direct Debit (R)
String (50)
Refund (R)
billTo_country
billTo_email
billTo_firstName
Country for the billing address. Possible
values are the two-character ISO Standard
Country Codes.
Direct Debit (R)
Customer’s email address, including the
full domain name. For example,
[email protected].
Direct Debit (R)
Direct Debit (R)
String (2)
Refund (R)
String (255)
Refund (R)
String (60)
Refund (R)
billTo_lastName
Direct Debit (R)
String (60)
Refund (R)
billTo_phoneNumber
Direct Debit (O)
String (15)
Refund (O)
billTo_postalCode
Postal code for the billing address. The
If the value of billTo_country is US, the 9digit postal code must follow this format:
Example: 12345-6789
Direct Debit (R if
billTo_country
is US or CA)
String (10)
Refund (R if
billTo_country
is US or CA)
If the value of billTo_country is CA, the 6digit postal code must follow this format:
Example: A1B 2C3
billTo_state
billTo_street1
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
Direct Debit (See
description)
Street address for the billing address.
Direct Debit (R)
String (2)
Refund (See
description)
String (60)
Refund (R)
119
Chapter 9
Table 37
Request Field
Description
Required (R)
or Optional
(O)
Data Type &
Length
billTo_street2
Additional street address information for
the billing address.
Direct Debit (O)
String (60)
directDebitRefundService_
directDebitRequestID
The requestID value returned from a
previous request for directDebitService.
Refund (R for
follow-on
refunds. Not
used for standalone refunds.)
String (26)
directDebitRefundService_
reconciliationID
To use this field, contact CyberSource
Customer Support.
Refund (R)
String (60)
directDebitRefundService_run
Flag indicating whether or not to include
the directDebitRefundService service in
your request. Possible values:
Refund (R)
String (5)

true: Include the service in your request

false (default): Do not include the
service in your request
Refund (O)
directDebitService_
dateCollect
Date on which the direct debit should be
debited. This field is only for the Global
Collect processor. Format: YYYYMMDD
Direct Debit (O)
Numeric (8)
directDebitService_
directDebitText
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.
Direct Debit (See
description)
String (See
description)
Direct Debit (See
description)
String (3)
Direct Debit (O)
Numeric (8)
Austria: Max 28 characters
Germany: Max 50 characters
Netherlands: Max 32 characters
Spain: Max 40 characters
directDebitService_
directDebitType
directDebitService_mandate
AuthenticationDate
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
120
Chapter 9
Table 37
Request Field
Description
Required (R)
or Optional
(O)
Data Type &
Length
directDebitService_
recurringType
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:
Direct Debit (See
description)
String (3)
Direct Debit (R)
String (5)
Direct Debit (See
description)
String (2)
Direct Debit (R)
String (30)
directDebitService_run
directDebitService_
transactionType

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.
fundTransfer_accountName
Name used on the bank account.
Refund (R)
121
Chapter 9
Table 37
Request Field
Description
Required (R)
or Optional
(O)
Data Type &
Length
fundTransfer_accountNumber
Direct Debit (See
description)
String (See
description)
Refund (See
description)
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
Direct Debit (See
description)
String (2)
fundTransfer_iban
Direct Debit (See
description)
Alphanumeric
(50)
Direct Debit (O)
String (30)
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.
Refund (O)
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,
Direct Debit (See
description)
String (30)
Refund (O)
122
Chapter 9
Table 37
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
description)
String (30)
The default is 1. For direct debits, required
if item_#_productCode is not default,
related to shipping or handling.
Direct Debit (See
description)
Tax amount associated with this item. The
field is additive. For example, if you send
one item with unitPrice of 10.00 and
taxAmount of 0.80, and you send another
item with unitPrice of 20.00 and
taxAmount of 1.60, the total amount
authorized will be for 32.40, not 30.00 with
2.40 of tax included.
Direct Debit (O)
item_#_quantity
item_#_taxAmount
Refund (O)
Integer (10)
Refund (O)
String (15)
Refund (O)
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
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
Order API.
Direct Debit (See
description)
String (15)
Refund (See
description)
truncated at the request level to the correct
number of decimal places.
123
Chapter 9
Table 37
Request Field
Description
Required (R)
or Optional
(O)
Data Type &
Length
linkToRequest
when multiple payment methods are being
used to complete an order. For more
information, see Credit Card Services
Direct Debit (O)
String (26)
merchantID
Direct Debit (R)
String (30)
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.
Refund (R)
tracking number. For more information, see
Direct Debit (R)
Currency used for the order. Possible
values are the ISO Standard Currency
Codes.
Direct Debit (R)
either this field or the item_#_unitPrice
field in your request. For more information,
see, Getting Started with CyberSource
Direct Debit (See
description)
shipTo_city
City of the shipping address.
Direct Debit
(Required if any
shipping
information is
included)
String (50)
shipTo_country
Country of the shipping address. Possible
values are the two-character ISO Standard
Country Codes.
Direct Debit (O)
String (2)
shipTo_firstName
First name of the person receiving the
product.
Direct Debit (O)
String (60)
shipTo_lastName
Last name of the person receiving the
product.
Direct Debit (O)
String (60)
purchaseTotals_
grandTotalAmount
String (50)
Refund (R)
String (5)
Refund (R)
String (15)
Refund (See
description)
124
Chapter 9
Table 37
Request Field
Description
Required (R)
or Optional
(O)
Data Type &
Length
shipTo_phoneNumber
Direct Debit (O)
String (15)
shipTo_postalCode
Postal code for the shipping address. The
Direct Debit (R if
shipTo_
country=US or
CA)
String (10)
If the value of shipTo_country is US, the
9-digit postal code must follow these rules:
Example: 12345-6789
If the value of shipTo_country is CA, the
6-digit postal code must follow these rules:
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
shipTo_state
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
Direct Debit (See
description)
String (2)
shipTo_street1
First line of the shipping address.
Direct Debit
(Required if any
shipping
information is
included)
String (60)
shipTo_street2
Direct Debit (O)
String (60)
125
Chapter 9
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
Refund
Alphanumeric
(50)
processorResponse
Refund
String (10)
reasonCode
Numeric value that indicates the result of
the direct debit refund request. See
"Reason Codes," page 155, for a list of
possible values.
Refund
Integer (5)
reconciliationID
Unique value generated by CyberSource.
For more information, see Getting Started
Order API.
Refund
String (60)
requestDateTime
Time of the direct debit refund request in
UTC.
Example: 2007-08-11T22: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
String (20)
directDebitReply_amount
Total amount for the direct debit.
Direct Debit
String (15)
directDebitReply_iban
Direct Debit
Alphanumeric
(50)
directDebitReply_mandateID
The identification reference for the direct
debit mandate.
Direct Debit
Alphanumeric
(16)
directDebitReply_
processorResponse
Direct Debit
String (10)
directDebitReply_reasonCode
the direct debit request. See "Reason
Codes," page 155, for a list of possible
values.
Direct Debit
Integer (5)
126
Chapter 9
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
Unique value generated by CyberSource.
For more information, see Getting Started
Order API.
Direct Debit
String (60)
directDebitReply_
requestDateTime
Time of the direct debit request in UTC.
Example: 2007-08-11T22: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.
Direct Debit
String (20)
invalidField_0...N
Fields in the request that contained invalid
data. These reply fields are included as an
Direct Debit
and Refund
String (100)
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
String (50)
missingField_0...N
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
Order API.
Direct Debit
and Refund
String (100)
Currency used for the order. Possible
values are the ISO Standard Currency
Codes.
Direct Debit
and Refund
String (5)
reasonCode
the overall request. See "Reason Codes,"
page 155, for a list of possible values.
Direct Debit
and Refund
Integer (5)
requestID
Identifier for the request.
Direct Debit
and Refund
String (26)
127
Chapter 9
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.
Note
Direct Debit Request
Example 41
<billTo>
<street1>Kaerntner Strasse 22</street1>
<city>Vienna</city>
<country>ES</country>
<phoneNumber>431427721010</phoneNumber>
</billTo>
<purchaseTotals>
</purchaseTotals>
<fundTransfer>
<bankCheckDigit>90</bankCheckDigit>
</fundTransfer>
<bankInfo>
<country>ES</country>
<branchCode>5394</branchCode>
<swiftCode>ABNA NL 2A</swiftCode>
</bankInfo>
<directDebitService run="true">
<directDebitText>abcd</directDebitText>
<directDebitType>004</directDebitType>
<mandateAuthenticationDate>20140610</mandateAuthenticationDate>
</directDebitService>
</requestMessage>
128
Chapter 9
Direct Debit Reply
Example 42
Direct Debit Reply
<c:purchaseTotals>
</c:purchaseTotals>
<c:directDebitReply>
<c:mandateID>159799546111146963</c:mandateID>
<c:iban>IE64BOFI0001155325</c:iban>
</c:directDebitReply>
</c:replyMessage>
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.
Note
Example 43
<billTo>
</billTo>
<purchaseTotals>
</purchaseTotals>
129
Chapter 9
<fundTransfer>
</fundTransfer>
<bankInfo>
</bankInfo>
<directDebitService run="">
</directDebitService>
<directDebitRefundService run="true"/>
</requestMessage>
Example 44
Standalone Direct Debit Refund Reply
<c:purchaseTotals>
</c:purchaseTotals>
<c:directDebitRefundReply>
<c:processorResponse>800</c:processorResponse>
<c:iban>DE58790500000044497071</c:iban>
</c:directDebitRefundReply>
</c:replyMessage>
Follow-On Direct Debit Refund
Example 45
Follow-On Direct Debit Refund Request
<purchaseTotals>
</purchaseTotals>
<directDebitRefundService run="true">
<directDebitRequestID>4024443213630181552683</directDebitRequestID>
</directDebitRefundService>
</requestMessage>
130
Chapter 9
Example 46
Follow-On Direct Debit Refund Reply
<c:purchaseTotals>
</c:purchaseTotals>
<c:directDebitRefundReply>
<c:iban>IE64BOFI0001155325</c:iban>
</c:directDebitRefundReply>
</c:replyMessage>
131
CHAPTER
Direct Debits and Direct
Debit Refunds Using the
SCMP API
Important
10
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.
Important
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
132
Chapter 10
rejects the request with a rflag=DINVALIDACCOUNT. CyberSource recommends that you
direct debit again with the correct number.
Important
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.

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,
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.

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.
133
Chapter 10
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.

Instead, CyberSource does not process the refund, and the transaction appears in the
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.
134
Chapter 10
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
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
Description
Required (R)
or Optional
(O)
Data Type
& Length
bank_account_
name
Name used on the bank account.
Direct Debit (O)
String (30)
bank_account_
number
Refund (O)
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,
2016.
Direct Debit
(See
description)
String (See
description)
Refund (See
description)
Note Do not use the IBAN in this field. include the
IBAN in the fundTransfer_iban field.
bank_address
Bank’s address.
Direct Debit (O)
String (255)
Refund (O)
bank_check_digit
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
Direct Debit
(See
description)
String (2)
bank_city
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.
Direct Debit (O)
String (35)
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.
Direct Debit
(See
description)
bank_code
Refund (O)
String (See
description)
Refund (See
description)
135
Chapter 10
Table 39
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)
String (2)
account.
Direct Debit
(See
description)
Alphanumeric
(50)
Direct Debit
(See
description)
String (40)
bank_iban
Important From August 1, 2016, for euro countries
Refund (R)
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,
2016.
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

Stand-alone direct debit refund
Refund (See
description)
Otherwise optional.
bank_swiftcode
Bank’s SWIFT code. Unique address of the bank. Also
known as the Bank Identification Code (BIC).
Direct Debit (O)
String (30)
Refund (O)
Note This field is optional; however, CyberSource
strongly recommends including this code in each
request when the IBAN is included in the request.
bill_address1
Direct Debit (R)
String (60)
Refund (R)
bill_address2
Direct Debit (O)
String (60)
Refund (O)
bill_city
Direct Debit (R)
String (50)
Refund (R)
bill_country
bill_state
Billing address country. Possible values are the twocharacter ISO Standard Country Codes.
Direct Debit (R)
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.
Direct Debit
(See
Description)
String (2)
Refund (R)
String (2)
Refund (See
Description)
136
Chapter 10
Table 39
Request-Level
Field
Description
Required (R)
or Optional
(O)
Data Type
& Length
bill_zip
Zip code for the shipping address. The zip code must
consist of 5 to 9 digits.
Direct Debit (R if
bill_
country=US or
CA)
String (10)
If the value of bill_country is US, the 9-digit zip code
must follow this format:
Example:12345-6789
If the value of bill_country is CA, the 6-digit zip code
must follow this format:
Example: A1B 2C3
Refund (R if
bill_
country=US or
CA)
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
Direct Debit
(See
description)
Currency used for the order. Possible values are the
ISO Standard Currency Codes.
Direct Debit (R)
Customer’s email address, including the full domain
name. For example, [email protected].
Direct Debit (R)
customer_
firstname
Direct Debit (R)
customer_
lastname
customer_phone
branch_code
currency
customer_email
String (15)
Refund (See
description)
String (5)
Refund (R)
String (255)
Refund (R)
String (60)
Refund (R)
Direct Debit (R)
String (60)
Refund (R)
Direct Debit (O)
String (15)
Refund (O)
date_collect
Date the direct debit should be debited.
Format: YYYYMMDD
Direct Debit (O)
String (8)
direct_debit_
mandate_
authentication_
date
The date the direct debit mandate was authenticated.
Format: YYYYMMDD
Direct Debit (O)
Numeric (8)
137
Chapter 10
Table 39
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
description)
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
The request_id value returned from a previous request
for ics_direct_debit.
Refund (R)
String (26)
direct_debit_text
Text describing reason for the direct debit. Required
only for the Global Collect processor. Appears on the
customer’s bank statement.
Direct Debit (R)
String (See
description)
Austria: Max 28 characters
Germany: Max 50 characters
Netherlands: Max 32 characters
Spain: Max 40 characters
direct_debit_
trans_ref_no
To use this field, contact CyberSource Customer
Support.
Refund (R)
String (60)
direct_debit_type
Type of direct debit. Required only for the Global Collect
processor. Possible values:
Direct Debit
(See
description)
String (3)
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
description)
Decimal (15)
Direct Debit (R)
grand_total_
amount
ics_applications

001: Austria

003: Netherlands

004: Spain

005: German ELV direct debit
Refund (See
description)
String (255)
Refund (R)
link_to_request
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.
Direct Debit (O)
String (26)
138
Chapter 10
Table 39
Request-Level
Field
Description
Required (R)
or Optional
(O)
Data Type
& Length
mandate_id
The mandate ID. Required only for the United Kingdom.
Direct Debit
(See
description)
String (16)
merchant_id
Direct Debit (R)
String (30)
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.
Refund (R)
merchant_ref_
number
number. For more information, see Getting Started with
Direct Debit (R)
offer0...N
Offers for the request. An offer is a line item for the
order.
Direct Debit (O)
ship_to_address1
First line of the shipping address. Required if any
shipping information is included.
Direct Debit
(See
description)
String (60)
ship_to_address2
Direct Debit (O)
String (60)
ship_to_city
City of the shipping address. Required if any shipping
information is included.
Direct Debit
(See
description)
String (50)
ship_to_country
Country of the shipping address. Possible values are
the two-character ISO Standard Country Codes.
Direct Debit (O)
String (2)
ship_to_firstname
Direct Debit (O)
String (60)
ship_to_lastname
Direct Debit (O)
String (60)
ship_to_phone
Direct Debit (O)
String (15)
ship_to_state
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.
Direct Debit
(See
description)
String (2)
String (50)
Refund (R)
String (50)
Refund (O)
139
Chapter 10
Table 39
Request-Level
Field
Description
Required (R)
or Optional
(O)
Data Type
& Length
ship_to_zip
Direct Debit (R if
ship_to_
country=US or
CA)
String (10)
Number of seconds until the transaction times out. The
default is 110 seconds.
Direct Debit (O)
Positive
integer (3)
Type of direct debit transaction. Required only for the
Netherlands when using the Global Collect processor.
Possible values:
Direct Debit
(See
description)
If the value of ship_to_country is US, the 9-digit zip
Example: 12345-6789
If the value of ship_to_country is CA, the 6-digit zip
Example: A1B 2C3
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
transaction_type

01: First collection using this account

02: Other
Refund (O)
String (2)
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.
140
Chapter 10
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)
Data
Type &
Length
amount
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.
Direct Debit (See
description)
Decimal
(15)
Refund (See
description)
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_code
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.
Direct Debit (See
description)
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.
Direct Debit (O)
String (30)
Refund (O)
String (30)
Refund (O)
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_name
quantity
Product’s name. For direct debits, required if
or handling.
Direct Debit (See
description)
Quantity of the product being purchased.The
default is 1. For direct debits, required if
or handling.
Direct Debit (See
description)
String (30)
Refund (O)
Refund (O)
Nonnegative
integer
(10)
141
Chapter 10
Table 40
Offer-Level Fields for Direct Debits and Direct Debit Refunds
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)
Decimal
(15)
Refund (O)
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
String (50)
Currency used for the order. Possible values are
the ISO Standard Currency Codes.
Direct Debit
direct_debit_amount
Amount of the direct debit.
Direct Debit
Decimal (15)
direct_debit_iban
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)
currency
Refund
String (5)
Refund
142
Chapter 10
Table 41
Reply Fields for Direct Debits and Direct Debit Refunds for the SCMP API (Continued)
Reply Field
Description
Returned
By
Data Type &
Length
iban
bank account.
Refund
Alphanumeric
(50)
rcode
One-digit code that indicates if the ics_direct_
debit_refund request was successful.
Refund
Integer (1)
request_time
Time of direct debit refund request in UTC. For
Refund
Date and time
(20)
response_code
Refund
String (10)
rflag
One-word description of the result of the ics_
direct_debit_refund request.
Refund
String (50)
rmsg
Message that explains the reply flag direct_debit_
refund_rflag.
Refund
String (255)
trans_ref_no
Reference number for the transaction. For more
Refund
String (60)
direct_debit_request_
time
Time of direct debit request in UTC. For more
Refund
Date and time
(20)
direct_debit_response_
code
Direct Debit
String (10)
direct_debit_rflag
One-word description of the result for the ics_
direct_debit request.
Direct Debit
String (50)
direct_debit_rmsg
Message that explains the reply flag direct_debit_
rflag.
Direct Debit
String (255)
direct_debit_trans_ref_
no
Reference number for the transaction. For more
Refund
String (60)
ics_rcode
One-digit code that indicates whether the entire
request was successful.
Direct Debit
and Refund
Integer (1)
ics_rflag
One-word description of the result for the entire
request.
Direct Debit
and Refund
String (50)
ics_rmsg
Direct Debit
and Refund
String (255)
merchant_ref_number
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
String (50)
request_id
Identifier for the request generated by the client.
Direct Debit
and Refund
String (26)
143
Chapter 10
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
Direct Debit
and Refund
DMISSINGFIELD
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
Direct Debit
and Refund
SOK
Direct Debit
and Refund
144
Chapter 10
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.
Note
Example 47
ics_applications=ics_direct_debit
bank_account_name=Direct_Debit Testing
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
[email protected]
customer_phone=999-999-9999
direct_debit_mandate_authentication_date=20140610
direct_debit_text=Direct Debit Text
direct_debit_type=001
145
Chapter 10
Example 48
Direct Debit Reply
currency=eur
direct_debit_amount=21.11
direct_debit_iban=IE64BOFI55500643635
direct_debit_mandate_id=697458823683278238
direct_debit_rcode=1
direct_debit_rflag=SOK
direct_debit_rmsg=Request was processed successfully.
direct_debit_time=2014-06-10T211943Z
direct_debit_trans_ref_no=2149562887
ics_decision_reason_code=100
ics_rcode=1
ics_rflag=SOK
request_id=4024351829300172492137
146
Chapter 10
Direct Debit Refund—Standalone
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.
Note
Example 49
ics_applications=ics_direct_debit_refund
bank_account_name=Direct_Debit Testing
bank_address=Vienna Central Branch
bank_check_digit=77
bank_code=31000
bank_country=AT
bank_name=Raiffeisen Zentral
bill_address1=PARK
bill_city=HINTERBRUHL
bill_country=AT
branch_code=99999
currency=EUR
[email protected]
customer_phone=999-999-9999
date_collect=20120821
direct_debit_text=Direct Debit Text
direct_debit_type=001
mandate_id=1
Example 50
Standalone Direct Debit Refund Reply
currency=eur
direct_debit_refund_amount=100.00
direct_debit_refund_iban=IE64BOFI55500643635
direct_debit_refund_rcode=1
direct_debit_refund_rflag=SOK
direct_debit_refund_rmsg=Request was processed successfully.
direct_debit_refund_time=2014-06-10T211934Z
direct_debit_refund_trans_ref_no=Reference No
ics_rcode=1
ics_rflag=SOK
request_id=4024351740870172492137
147
Chapter 10
Direct Debit Refund—Follow-On
Example 51
Follow-On Direct Debit Refund Request
ics_applications=ics_direct_debit_refund
direct_debit_request_id=4024351829300172492137
Example 52
Follow-On Direct Debit Refund Reply
currency=eur
direct_debit_refund_amount=21.11
direct_debit_refund_iban=IE64BOFI55500643635
direct_debit_refund_rcode=1
direct_debit_refund_rflag=SOK
direct_debit_refund_rmsg=Request was processed successfully.
direct_debit_refund_time=2014-06-10T211943Z
direct_debit_refund_trans_ref_no=2149562887
ics_rcode=1
ics_rflag=SOK
request_id=4024351832340172492137
148
CHAPTER
Testing
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:
https://ics2wstest.ic3.com/commerce/1.x/transactionProcessor

When testing the SCMP API, use the CyberSource test server:
https://ics2test.ic3.com
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 description).
149
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
2013
233
DINVALIDDATA
No bank found for this country
Bank Transfer
2014
233
DINVALIDDATA
Invalid bank account number
Bank Transfer
Direct Debit
2015
233
DINVALIDDATA
Invalid Post giro account number
Bank Transfer
Direct Debit
2020
233
DINVALIDDATA
Authorization ID is required for country.
Direct Debit
2024
233
DINVALIDDATA
Bank code is required for country
Direct Debit
2025
233
DINVALIDDATA
Account name is required for country
Direct Debit
2026
233
DINVALIDDATA
Account number is required for country
Direct Debit
2027
233
DINVALIDDATA
Direct debit text is required for country
Direct Debit
2028
233
DINVALIDDATA
Date collect is required for country
Direct Debit
2029
233
DINVALIDDATA
Bank check digit is required for country
Direct Debit
2030
233
DINVALIDDATA
Branch code is required for country
Direct Debit
2031
233
DINVALIDDATA
Bank name is required for country
Direct Debit
2032
233
DINVALIDDATA
Date collected.
Direct Debit
2033
233
DINVALIDDATA
Account number has invalid length
Direct Debit
2034
233
DINVALIDDATA
Invalid bank code for payment type and
country combination
Direct Debit
2035
233
DINVALIDDATA
Bank code does not match bank name
Direct Debit
2036
233
DINVALIDDATA
Invalid bank account number
Bank Transfer
Direct Debit
2037
233
DINVALIDDATA
Invalid Post giro account number
Bank Transfer
Direct Debit
2038
2039
233
233
DINVALIDDATA
DINVALIDDATA
Amount not between minimum and
maximum amounts
Bank Transfer
Payment type invalid for country code
Bank Transfer
Direct Debit
Direct Debit
150
Chapter 11
Table 43
Testing
Test Data for Global Payment Service (Continued)
Amount
Simple
Order API
Reason
Code
SCMP API
rflag
SCMP API rmsg Description
Used with
These Payment
Types
2042
237
DINVALIDDATA
Already refunded; no multiple refunds
allowed
Bank Transfer
Refund
Direct Debit
Refund
2044
239
DINVALIDDATA
Refund amount too large
Bank Transfer
Refund
Direct Debit
Refund
2045
150
ESYSTEM
The request refers to an unknown order.
Bank Transfer
Refund
Direct Debit
Refund
9999.98
250
ETIMEOUT
Time-out connecting to processor
All
9999.99
150
ESYSTEM
Unexpected error
All
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.
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.
Important
151
Chapter 11
Testing
Testing Your Network Interface
This stage of testing is available only for the real-time bank transfer networks in
the following table.
Note
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
Description
eNets
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.
GiroPay (Germany)
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.
iDEAL (Netherlands)
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.
Nordea e-betaling (Denmark)
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.
Nordea e-betalning (Sweden)
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.
Nordea e-maksu (Finland)
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
Contact Customer Support to have your connection switched to the network’s simulator.
Step 2
Set up a test customer that consists of a browser that interfaces with your shopping cart.
Step 3
Simulate the customer experience by having your test customer initiate a real-time bank
transfer payment.
Step 4
When you receive this customer message, send a real-time bank transfer request to
CyberSource.
Step 5
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.
152
Chapter 11
Step 6
Testing
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:
https://ebc.cybersource.com
153
APPENDIX
Product Codes
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
Definition
adult_content
Adult content.
coupon
Coupon applied to the entire order.
default
Default value for the product code. CyberSource uses default when a request
provides no value for the product code.
electronic_good
Electronic product other than software.
electronic_software
Software distributed electronically rather than on tapes, disks, or other media.
gift_certificate
Gift certificate not issued with CyberSource Stored Value Services.
handling_only
Separate charge that is generally a fee imposed by the seller on the customer.
The fee pays the seller’s administrative selling costs.
service
Service that you perform for the customer.
shipping_and_handling
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.
shipping_only
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
Subscription to a web site or other content.
154
APPENDIX
Reason Codes
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
Table 46
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.
Reason Codes for the Simple Order API
Reason
Code
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.
155
Appendix B
Table 46
Reason Codes
Reason Codes for the Simple Order API (Continued)
Reason
Code
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.
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.
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.
156
Appendix B
Table 46
Reason Codes
Reason Codes for the Simple Order API (Continued)
Reason
Code
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.
157
APPENDIX
Researching a Missing Bank
Transfer Payment
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).
158
Appendix C
Researching a Missing Bank Transfer Payment
To research a missing payment:
Step 1
Log in to the Business Center and search for the bank transfer transaction.
Step 2
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.
159
Appendix C
Researching a Missing Bank Transfer Payment
Step 4
In the Merchant Information section, enter your contact information. CyberSource uses
this information to contact you if more information is needed.
Step 5
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
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.
Step 7
In the Other Information field, include any other information that might help CyberSource
research the missing payment.
Step 8
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 email 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 email or phone.
160
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
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
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
C
check reference numbers 13
coupons 154
D
date and time format
Simple Order API 27
direct debit refunds
SCMP API 133
bankTransferRefundService 16
direct debits
and direct debit refunds
SCMP API 132
examples
SCMP API 95
Simple Order API 88, 128, 145
requesting
SCMP API 132
bankTransferService 15
directDebitRefundService 116
boletoPaymentService 84
directDebitService 115
bank transfers, real-time. See real-time bank
transfers
bankTransferRealTimeService 54
Boletos Bancários
description of
161
Index
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
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
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
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
162
Index
requesting
SCMP API 70
Simple Order API 54
transaction statuses
SCMP API 67
Simple Order API 51
reason codes
listed 155
SCMP API 134
transaction reference numbers 13
U
UTC format
Simple Order API 27
reconciliation IDs 13
refunds
bank transfers
SCMP API 34
Simple Order API 16
direct debits
SCMP API 133
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
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
163

Global Payment Service Developer Guide

Transcription

Similar documents

The Easy Refund Card… - Indian Hills Community College

Gabe Westmaas Rackspace @westmaas

Help Document Open the URL – www.irctc.co.in Enter your login

Sze Wong | CEO | Zerion Software, Inc.

Direct Payment Form

School Spirit Visa® Debit Cards

Payment Error Guide - Texas Tech University

Direct Deposit Your 2008 IRS Tax Refund

returns form - Beadazzle Boutique

to the PDF file.