On This Page

Online Bank Transfers Developer Guide

This section describes how to use this guide and where to find further information.

Audience and Purpose

This guide is written for merchants who want to offer Online Bank Transfer services to customers and describes tasks a merchant must complete in order to make a payment, request the status of a payment, or refund a payment. It is intended to help the merchant provide a seamless customer payment experience.

Conventions

The following special statement is used in this document:
An
Important
 statement contains information essential to successfully completing a task or learning a concept.

Related Documentation

Refer to the Technical Documentation Hub in the Cybersource Developer Center for additional technical documentation:

Customer Support

For support information about any service, visit the Support Center:

Recent Revisions to This Document

24.02

The guide has undergone a major reorganization.

24.01

Removed references to no longer supported payment methods.

20.02

Added Handelsbanken and Moneyou to the list of banks that support iDEAL payment method transactions.
Updated iDeal examples for transactions using Handelsbanken and Moneyou, see Example: Refunding a Payment.

Introduction to Online Bank Transfers

Online Bank Transfer services enables customers to pay for goods and services using online bank transfers from their bank accounts directly to your account.

Supported Payment Methods

Online Bank Transfers enables you to process transactions using these payment services:
  • Bancontact: e-commerce payment system in Belgium. It enables customers to pay for goods using direct bank transfers from their bank accounts directly to your account.
  • iDEAL: e-commerce payment system in the Netherlands. It enables customers to pay for goods using online bank transfers from their bank accounts directly to your account.

Bancontact

Bancontact is an e-commerce payment system in Belgium. It enables customers to pay for goods using direct bank transfers from their bank accounts directly to your account.
These banks support the Bancontact payment method:
  • ABK Bank
  • Argenta
  • Axa
  • Bank VanBreda
  • CPH Banque
  • Belfius
  • Beobank
  • BNP Paribas Fortis
  • Bpost Bank
  • CBC
  • Crelan
  • Deutsche Bank
  • ING
  • KBC
  • Keytrade Bank
  • Nagelmackers
  • Record Bank
  • VDK Spaarbank

iDEAL

iDEAL is an e-commerce payment system in the Netherlands. It enables customers to pay for goods using online bank transfers from their bank accounts directly to your account.
Following is a list of banks that support the iDEAL payment method and their option IDs.
  • ABN AMRO: ABNCNL2A
  • ASN Bank: ASNBNL21
  • Bunq: BUNQNL2A
  • Handelsbanken: HANDNL2A
  • ING Bank: INGBNL2A
  • Knab: KNABNL2H
  • Moneyou: MOYONLI21
  • Rabobank: RABONL2URSA
  • RegioBank: RBRBNL21
  • SNS Bank: SNSBNL2A
  • Triodos Bank: TRIONL2U
  • Van Lanschot: FVLBNL22
Cybersource
 recommends that you make the iDEAL payment method available to Belgian customers. A large number of Dutch nationals or Dutch bank account holders resides in Belgium, and they prefer to use their Dutch accounts.

Payment Method Workflows

This section describes the workflows for the different Online Bank Transfer payment methods.

Bancontact Workflow

This workflow describes the sequence of events that comprise a successful Bancontact transaction.
  1. The customer begins to checkout using Bancontact as a payment method and selects their bank.
  2. The merchant sends a sale API request to
    Cybersource
    . For more information, see Processing a Sale.
  3. Cybersource
     sends a
    pending
     status and a redirect URL to the merchant.
  4. The merchant redirects the customer to their issuing bank's website.
  5. The customer enters their Bancontact card information and is redirected to the merchant's success URL.
  6. The merchant displays payment confirmation to the customer.
  7. To confirm the updated payment status, the merchant sends a check status API request to
    Cybersource
     and includes the sale request ID. For more information, see Check Transaction Status.
  8. Cybersource
     sends a
    settled
     status to the merchant.

Bancontact Refund Workflow

This workflow describes the sequence of events that comprise a successful Bancontact refund.
  1. The customer initiates a refund to the merchant.
  2. The merchant sends a refund API request to
    Cybersource
     and includes the sale request ID. For more information, see Refund a Payment.
  3. Cybersource
     sends either a
    pending
     or
    refunded
     status to the merchant.
  4. The merchant displays refund confirmation to the customer.
  5. To confirm the updated refund status, the merchant sends a check status API request to
    Cybersource
     and includes the refund request ID. For more information, see Check Transaction Status.
  6. Cybersource
     sends a
    refunded
     status to the merchant.

iDEAL Workflow

This workflow describes the sequence of events that comprise a successful iDEAL transaction.
  1. The customer begins to checkout using iDEAL as a payment method and selects their bank.
  2. The merchant sends a sale API request to
    Cybersource
    . For more information, see Processing a Sale.
  3. Cybersource
     sends a
    pending
     status and a redirect URL to the merchant.
  4. The merchant redirects the customer to their issuing bank's website.
  5. The customer enters their payment information and is redirected to the merchant's success URL.
  6. The merchant displays payment confirmation to the customer.
  7. To confirm the updated payment status, the merchant sends a check status API request to
    Cybersource
    . For more information, see Check Transaction Status.
  8. Cybersource
     sends a
    settled
     status to the merchant.

iDEAL Refund Workflow

This workflow describes the sequence of events that comprise a successful iDEAL refund.
  1. The customer initiates a refund to the merchant.
  2. The merchant sends a refund API request to
    Cybersource
     and includes the sale request ID. For more information, see Refund a Payment.
  3. Cybersource
     sends either a
    pending
     or
    refunded
     status to the merchant.
  4. The merchant displays refund confirmation to the customer.
  5. To confirm the updated refund status, the merchant sends a check status API request to
    Cybersource
     and includes the refund request ID. For more information, see Check Transaction Status.
  6. Cybersource
     sends a
    refunded
     status to the merchant.

Merchant Account Types

There are two types of Cybersource merchant accounts,
Cybersource
 settlement services accounts
 and
processor direct contract accounts
.

Cybersource
 Settlement Services Account

This merchant account has no direct contract with a payment provider partner. The
Cybersource
 Financial Settlement Partner (FSP) collects funds on your behalf and settles them to your merchant account.
Cybersource
 requests the export compliance service for every transaction using the
Cybersource
 settlement services account. The export compliance service compares customer information to export control lists maintained by government agencies. If a customer's name appears on any government list, the transaction is declined.
To facilitate compliance checks for
Cybersource
 settlement services accounts, you must include these fields in your authorization service requests.
You must include these fields in the live environment to avoid receiving error messages.

Figure:

Mandatory Authorization Fields for a
Cybersource
 Settlement Services Account
billTo_city
billTo_country
billTo_firstName
billTo_lastName
billTo_street1

Processor Direct Contract Account

This merchant account must use the payment provider selected by
Cybersource
. If you have existing direct contracts, you must inform your sales representative.

Line Items

The Online Bank Transfer services use line items when you send a sale or refund request. Line items are used to include information about the goods that your customers purchase, such as product name, quantity, and price.
Line items are represented as the
item_#_
 fields, starting with
item_0_
, and increasing in numerical order.
These fields are required for each line item that you use:
item_#_productCode
item_#_productDescription
item_#_productName
item_#_quantity
item_#_unitPrice
Including Line Items in a Service Request
This example shows three valid line items.
<item id="0">
	<productCode>123456</productCode>
	<productDescription>Red</productDescription>
	<productName>Shirt</productName>
	<quantity>1</quantity>
	<unitPrice>30.00</unitPrice>
</item>
<item id="1">
	<productCode>456789</productCode>
	<productDescription>Green</productDescription>
	<productName>Pants</productName>
	<quantity>3</quantity>
	<unitPrice>19.99</unitPrice>
</item>
<item id="2">
	<productCode>987654</productCode>
	<productDescription>Blue</productDescription>
	<productName>Dress</productName>
	<quantity>2</quantity>
	<unitPrice>25.50</unitPrice>
</item>

Processing Bancontact Transactions

This section provides the information you need in order to process a Boncantact transaction.
The Bancontact payment method allows for the following processes:
  • Processing a Sale
  • Refunding a Payment
  • Checking a Transaction Status

Processing a Sale

The sale service responds with the redirect URL for the customer’s bank. The customer is directed to the URL to confirm their payment details.
The sale service requires you to include three redirect URLs in request. The URL to which the customer is directed is determined by the result of the sale process:
successURL
Set to the URL to which the customer is redirected after completing a payment. Do not use this URL to confirm a payment because the reply is not signed and it could be tampered with.
Cybersource
 recommends that the success URL link to a static web page with text that tells the customer their payment is being processed. A follow-up email or web page can then be used to inform them when their payment is successful.
cancelURL
Set to the URL to which the customer is redirected after canceling a payment or closing the browser.
failureURL
Set to the URL to which the customer is redirected when a payment fails because of insufficient funds or because the issuer declines it.
Cybersource
 can update your configuration settings to include the success, cancel, and failure URLs in your
Cybersource
 service requests. To update your configuration to include these URLs, contact your
Cybersource
 account representative.

Endpoints

Set the
apSaleService_run
 field to
true
, and send the request to one of these endpoints:
Production:
https://ics2ws.ic3.com/commerce/1.x/transactionProcessor
Test:
https://ics2wstest.ic3.com/commerce/1.x/transactionProcessor

Required Fields for a Sale

The type of
Cybersource
 merchant account you have determines which API fields are required.
apPaymentType
Set to
MCH
.
apSaleService_cancelURL
Required when your
Cybersource
 account does not include this value.
apSaleService_successURL
Required when your
Cybersource
 account does not include this value.
apSaleService_failureURL
Required when your
Cybersource
 account does not include this value.
apSaleService_run
Set to
true
.
invoiceHeader_merchantDescriptor
merchantID
merchantReferenceCode
purchaseTotals_currency
Set to
EUR
.
purchaseTotals_grandTotalAmount

Required Fields for
Cybersource
 Settlement Services Accounts

If you have a
Cybersource
 Settlement Services Account, include these required fields in addition to the required fields listed above.
billTo_city
billTo_country
billTo_firstName
billTo_lastName
billTo_street1

Optional Fields

item_#_productCode
item_#_productDescription
item_#_productName
item_#_quantity
item_#_unitPrice

Example: Processing a Sale

Sale Service Request
<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.126">
   <merchantID>mid43210</merchantID>
   <merchantReferenceCode>refnum1234</merchantReferenceCode>
   <invoiceHeader>
      <merchantDescriptor>Online Store</merchantDescriptor>
   </invoiceHeader>
   <purchaseTotals>
      <currency>EUR</currency>
      <grandTotalAmount>20.00</grandTotalAmount>
   </purchaseTotals>
   <apPaymentType>MCH</apPaymentType>
   <apSaleService run="true">
      <cancelURL>https://www.redirect.url.html?action=cancel</cancelURL>
      <successURL>https://www.redirect.url.html?action=success</successURL>
      <failureURL>https://www.redirect.url.html?action=failure</failureURL>
   </apSaleService>
</requestMessage>
Response to a Successful Sale Service Request
<replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.126">
   <merchantReferenceCode>refnum1234</merchantReferenceCode>
   <requestID>4703329437356002101200</requestID>
   <decision>ACCEPT</decision>
   <reasonCode>100</reasonCode>
   <purchaseTotals>
      <currency>EUR</currency>
   </purchaseTotals>
   <apSaleReply>
      <reasonCode>100</reasonCode>
      <paymentStatus>pending</paymentStatus>
      <responseCode>00001</responseCode>
      <merchantURL>https://merchant.redirect.com/url.do?param utf=%27%22%3C%3E
      %20%E6%B8%AC%E8%A9%A6%E6%B8%AC¶m_url=https%3A%2F%2F
      www.abc.com¶m_special=+@#%~_&sign=fdaa1df42b6260a10e2e3f1c0fc</merchantURL>
      <processorTransactionID>007055</processorTransactionID>
      <reconciliationID>9530019443</reconciliationID>
      <amount>20.00</amount>
      <processorResponse>0000001</processorResponse>
      <dateTime>2020-01-11T12:47:19Z</dateTime>
   </apSaleReply>
</replyMessage>
Sale Service Request (
Cybersource
 Settlement Services Account)
<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.126">
   <merchantID>mid43210</merchantID>
   <merchantReferenceCode>refnum1234</merchantReferenceCode>
   <invoiceHeader>
      <merchantDescriptor>Online Store</merchantDescriptor>
   </invoiceHeader>
   <billTo>
      <firstName>John</firstName>
      <lastName>Smith</lastName>
      <street1>10 TheStreet</street1>
      <city>Brussels</city>
      <country>BE</country>
   </billTo>
   <purchaseTotals>
      <currency>EUR</currency>
      <grandTotalAmount>20.00</grandTotalAmount>
   </purchaseTotals>
   <apPaymentType>MCH</apPaymentType>
   <apSaleService run="true">
      <cancelURL>https://www.redirect.url.html?action=cancel</cancelURL>
      <successURL>https://www.redirect.url.html?action=success</successURL>
      <failureURL>https://www.redirect.url.html?action=failure</failureURL>
   </apSaleService>
</requestMessage>
Sale Service Request (
Cybersource
 Settlement Services Account)
<replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.126">
   <merchantReferenceCode>refnum1234</merchantReferenceCode>
   <requestID>4703329437356002101200</requestID>
   <decision>ACCEPT</decision>
   <reasonCode>100</reasonCode>
   <purchaseTotals>
      <currency>EUR</currency>
   </purchaseTotals>
   <apSaleReply>
      <reasonCode>100</reasonCode>
      <paymentStatus>pending</paymentStatus>
      <responseCode>00001</responseCode>
      <merchantURL>https://merchant.redirect.com/url.do?param utf=
      %27%22%3C%3E%20%E6%B8%AC%E8%A9%A6%E6%B8%AC¶m_url=https%3A%2F%2F
      www.abc.com¶m_special=+@#%~_&sign=fdaa1df42b6260a10e2e3f1c0fc</merchantURL>
      <processorTransactionID>007055</processorTransactionID>
      <reconciliationID>9530019443</reconciliationID>
      <amount>20.00</amount>
      <processorResponse>0000001</processorResponse>
      <dateTime>2020-01-11T12:47:19Z</dateTime>
   </apSaleReply>
</replyMessage>

Refund a Payment

This section provides the information you need in order to process a refund, which is linked to a capture or sale. Bancontact transactions support:
  • Refunds of payments that have a status of settled.
  • Partial refunds and multiple refunds.
  • Refunds for the original payment amount and the addition of 25 EUR. If the original payment amount was 45 EUR, you can refund up to 70 EUR.
The refund service request is a follow-on request that uses the request ID value returned in the sale service reply. The request ID value links the refund transaction to the original payment transaction.
Before refunding a payment and returning funds to the customer account, the payment status must be settled. You must request a refund within 180 days of the authorization.

Endpoints

Set the
apRefundService_run
 field to
true
, and send the request to one of these endpoints:
Production:
https://ics2ws.ic3.com/commerce/1.x/transactionProcessor
Test:
https://ics2wstest.ic3.com/commerce/1.x/transactionProcessor

Required Fields for Refunding a Payment

apPaymentType
Set to
MCH
.
apRefundService_refundRequestID
Include the value of the
requestID
 field that was returned in the sale service reply.
apRefundService_run
Set to
true
.
merchantID
merchantReferenceCode
purchaseTotals_currency
purchaseTotals_grandTotalAmount

Example: Refunding a Payment

Refund Service Request
<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.126">
   <merchantID>mid43210</merchantID>   
   <merchantReferenceCode>refnum1234</merchantReferenceCode>
   <purchaseTotals>
      <currency>EUR</currency>
      <grandTotalAmount>20.00</grandTotalAmount>
   </purchaseTotals>
   <apPaymentType>MCH</apPaymentType>
   <apRefundService run="true">      
      <refundRequestID>4703329437356002101200</refundRequestID>
   </apRefundService>
</requestMessage>
Response to a Successful Refund Service Request
<replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.126">
   <merchantReferenceCode>refnum1234</merchantReferenceCode>
   <requestID>8484832012000483918274</requestID>
   <decision>ACCEPT</decision>
   <reasonCode>100</reasonCode>
   <purchaseTotals>
      <currency>EUR</currency>
   </purchaseTotals>
   <apRefundReply>
      <reasonCode>100</reasonCode>
      <status>refunded</status>
      <processorResponse>0000006</processorResponse>
      <amount>20.00</amount>
      <dateTime>2020-01-11T15:43:01Z</dateTime>
      <reconciliationID>01950351</reconciliationID>
      <processorTransactionID>903344</processorTransactionID>
      <paymentStatus>completed</paymentStatus>
      <responseCode>00006</responseCode>
   </apRefundReply>
</replyMessage>

Check Transaction Status

Request the check status service when the authorization status is pending.
The check status service returns the latest status of a transaction. The request ID links the check status request to the payment or refund transaction.
  • To check the status of the sale service, include the request ID value returned in the sale service reply.
  • To check the status of the refund service, include the request ID value returned in the refund service reply.
Cybersource
 recommends waiting 30 seconds before requesting the check status service.
If the check status reply is pending, wait 5 minutes before making the check status request again. If there is still no status change, wait 20 minutes before making another check status request. After 20 minutes, the status should be
settled
,
abandoned
, or
failed
.
When the payment is confirmed, the customer is directed to your success URL. Your success URL should point to a static web page that confirms the order is being processed. When the payment completes, notify the customer using email or a dedicated web page.
Do not ship your goods until the payment status is
settled
.

Endpoints

Set the
apCheckStatusService_run
 field to
true
, and send the request to one of these endpoints:
Production:
https://ics2ws.ic3.com/commerce/1.x/transactionProcessor
Test:
https://ics2wstest.ic3.com/commerce/1.x/transactionProcessor

Response Statuses

The check status service responds with one of these statuses in the
apCheckStatusReply_paymentStatus
 field.
  • Abandoned
    : the customer did not complete the transaction within 15 minutes.
  • Failed
    : the payment failed. Look at the
    reasonCode
    ics_rmsg
     field for a description.
  • Pending
    : the payment was initiated. Do not ship the goods.
  • Settled
    : the payment is complete. You can ship the goods.
The check status service also responds with a reason code in the
apCheckStatusReply_reasonCode
 field. For more information about reason codes, see the Reason Codes and Response Codes for the Simple Order API.

Required Fields for Checking Transaction Status

apCheckStatusService_checkStatusRequestID
To check the status of a sale, include the value of the
requestID
 field that was returned in the sale service reply.
apPaymentType
Set to
MCH
.
merchantID
merchantReferenceCode

Example: Checking Transaction Status

Check Transaction Status Service Request
<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.126">
   <merchantID>mid43210</merchantID>
   <merchantReferenceCode>refnum1234</merchantReferenceCode>
   <apPaymentType>MCH</apPaymentType>
   <apCheckStatusService run="true">
      <checkStatusRequestID>4703329437356002101200</checkStatusRequestID>
   </apCheckStatusService>
</requestMessage>
Response to a Successful Check Transaction Status Service Request
<replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.126">
   <merchantReferenceCode>refnum1234</merchantReferenceCode>
   <requestID>52391098509302958393020294</requestID>
   <decision>ACCEPT</decision>
   <reasonCode>100</reasonCode>
   <apCheckStatusReply>
      <reasonCode>100</reasonCode>
      <reconciliationID>TC38480966</reconciliationID>
      <paymentStatus>settled</paymentStatus>
      <processorResponse>000004</processorResponse>
      <dateTime>2020-01-11T15:16:14Z</dateTime>
   </apCheckStatusReply>
</replyMessage>

Processing iDEAL Transactions

This section provides the information you need in order to process a iDEAL transaction.
The iDEAL payment method allows for the following processes:
  • Requesting Options
  • Processing a Sale
  • Refunding a Payment
  • Checking a Transaction Status

Request Options

The options service retrieves a list of bank option IDs and bank names which you can display to the customer on your web site.
Request the options service once each day, at any time, to retrieve the list of bank names. Each name represents the bank identification code (BIC, also known as a
swift code
) associated with the bank and is prefixed with
ideal
, for example: ideal-BUNQNL2A.
Cybersource
 recommends caching the information and displaying the bank name to the customer in a drop-down menu on your checkout page. The customer chooses the iDEAL payment method and chooses their bank from the list of options that you have cached.
A list of all available banks can be displayed in a drop-down menu in any order you choose.
Cybersource
 recommends displaying the following six bank names and their logos at the top of the list:
  • ING Bank
  • Rabobank
  • ABN AMRO
  • SNS Bank
  • ASN Bank
  • Triodos Bank
When a customer chooses a bank on your web site, you must include the associated option ID in the sale request (see Processing a Sale). This returns a bank redirect URL, which steers the customer to the bank they have chosen. If the option ID is not included in the sale request, the bank redirect URL directs the customer to a bank selection page.

Endpoints

Set the
apOptionsService_run
 field to
true
, and send the request to one of these endpoints:
Production:
https://ics2ws.ic3.com/commerce/1.x/transactionProcessor
Test:
https://ics2wstest.ic3.com/commerce/1.x/transactionProcessor

Required Fields for Requesting Options

apPaymentType
Set to
IDL
.
apOptionsService_run
Set to
true
.
merchantID
merchantReferenceCode

Example: Requesting Options

Request Options
<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.158">
    <merchantID>abcd_1234</merchantID>
    <merchantReferenceCode>refnum1234</merchantReferenceCode>
    <apPaymentType>IDL</apPaymentType>
    <apOptionsService run="true"/>
    </apOptionsService>
</requestMessage>
Response to a Successful Options Request
<replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.158">
    <merchantReferenceCode>refnum1234</merchantReferenceCode>
    <requestID>4703329437356002101200</requestID>
    <decision>ACCEPT</decision>
    <reasonCode>100</reasonCode>
        <apOptionsReply>
                <reasonCode>100</reasonCode>
                <responseCode>00000</responseCode>
                <offset>0</offset>
                <count>12</count>
                <totalCount>12</totalCount>
                <option data="0">
                    <id>ideal-FVLBNL22</id>
                    <name>van Lanschot</name>
                </option>
                <option data="1">
                    <id>ideal-TRIONL2U</id>
                    <name>Triodos Bank</name>
                </option>
                <option data="2">
                    <id>ideal-SNSBNL2A</id>
                    <name>SNS</name>
                </option>
                <option data="3">
                    <id>ideal-RBRBNL21</id>
                    <name>RegioBank</name>
                </option>
                <option data="4">
                    <id>ideal-MOYONL21</id>
                    <name>Moneyou</name>
                </option>
                <option data="5">
                    <id>ideal-KNABNL2H</id>
                    <name>Knab</name>
                </option>
                <option data="6">
                    <id>ideal-HANDNL2A</id>
                    <name>Handelsbanken</name>
                </option>
                <option data="7">
                    <id>ideal-BUNQNL2A</id>
                    <name>bunq</name>
                </option>
                <option data="8">
                    <id>ideal-ASNBNL21</id>
                    <name>ASN Bank</name>
                </option>
                <option data="9">
                    <id>ideal-RABONL2U</id>
                    <name>Rabobank</name>
                </option>
                    <option data="10">
                    <id>ideal-INGBNL2A</id>
                    <name>ING</name>
                </option>
                <option data="11">
                    <id>ideal-ABNANL2A</id>
                    <name>ABN AMRO</name>
                </option>
        </apOptionsReply>
</replyMessage>

Processing a Sale

A sale transaction combines an authorization and a capture into a single transaction.
The sale service responds with the redirect URL for the customer’s bank. The customer is directed to the URL to confirm their payment details.
The sale service requires you to include three redirect URLs in request. The URL to which the customer is directed is determined by the result of the sale process:
successURL
Set to the URL to which the customer is redirected after completing a payment. Do not use this URL to confirm a payment because the reply is not signed and it could be tampered with.
Cybersource
 recommends that the success URL link to a static web page with text that tells the customer their payment is being processed. A follow-up email or web page can then be used to inform them when their payment is successful.
cancelURL
Set to the URL to which the customer is redirected after canceling a payment or closing the browser.
failureURL
Set to the URL to which the customer is redirected when a payment fails because of insufficient funds or because the issuer declines it.
Cybersource
 can update your configuration settings to include the success, cancel, and failure URLs in your
Cybersource
 service requests. To update your configuration to include these URLs, contact your
Cybersource
 account representative.

Endpoints

Set the
apSaleService_run
 field to
true
, and send the request to one of these endpoints:
Production:
https://ics2ws.ic3.com/commerce/1.x/transactionProcessor
Test:
https://ics2wstest.ic3.com/commerce/1.x/transactionProcessor

Required Fields for a Sale

The type of
Cybersource
 merchant account you have determines which API fields are required.
apPaymentType
Set to
IDL
.
apSaleService_cancelURL
Required when your
Cybersource
 account does not include this value.
apSaleService_successURL
Required when your
Cybersource
 account does not include this value.
apSaleService_failureURL
Required when your
Cybersource
 account does not include this value.
apSaleService_run
Set to
true
.
invoiceHeader_merchantDescriptor
merchantID
merchantReferenceCode
purchaseTotals_currency
purchaseTotals_grandTotalAmount

Required Fields for
Cybersource
 Settlement Services Accounts

If you have a
Cybersource
 Settlement Services Account, include these required fields in addition to the required fields listed above.
billTo_city
billTo_country
billTo_firstName
billTo_lastName
billTo_street1

Example: Processing a Sale

Sale Service Request
<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.126">
   <merchantID>mid43210</merchantID>
   <merchantReferenceCode>refnum1234</merchantReferenceCode>
   <invoiceHeader>
      <merchantDescriptor>Online Store</merchantDescriptor>
   </invoiceHeader>
   <purchaseTotals>
      <currency>EUR</currency>
      <grandTotalAmount>20.00</grandTotalAmount>
   </purchaseTotals>
   <apPaymentType>IDL</apPaymentType>
   <apSaleService run="true">
      <cancelURL>https://www.redirect.url.html?action=cancel</cancelURL>
      <successURL>https://www.redirect.url.html?action=success</successURL>
      <failureURL>https://www.redirect.url.html?action=failure</failureURL>
   </apSaleService>
</requestMessage>
Response to a Successful Sale Service Request
<replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.126">
   <merchantReferenceCode>refnum1234</merchantReferenceCode>
   <requestID>4703329437356002101200</requestID>
   <decision>ACCEPT</decision>
   <reasonCode>100</reasonCode>
   <purchaseTotals>
      <currency>EUR</currency>
   </purchaseTotals>
   <apSaleReply>
      <reasonCode>100</reasonCode>
      <paymentStatus>pending</paymentStatus>
      <responseCode>00001</responseCode>
      <merchantURL>https://merchant.redirect.com/url.do?param utf=%27%22%3C%3E

      %20%E6%B8%AC%E8%A9%A6%E6%B8%AC¶m_url=https%3A%2F%2F

      www.abc.com¶m_special=+@#%~_&sign=fdaa1df42b6260a10e2e3f1c0fc</merchantURL>
      <processorTransacationID>007055</processorTransactionID>
      <reconciliationID>9530019443</reconciliationID>
      <amount>20.00</amount>
      <processorResponse>0000001</processorResponse>
      <dateTime>2020-01-11T12:47:19Z</dateTime>
   </apSaleReply>
</replyMessage>
Sale Service Request (
Cybersource
 Settlement Services Account)
<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.126">
   <merchantID>mid43210</merchantID>
   <merchantReferenceCode>refnum1234</merchantReferenceCode>
   <invoiceHeader>
      <merchantDescriptor>Online Store</merchantDescriptor>
   </invoiceHeader>
   <billTo>
      <firstName>John</firstName>
      <lastName>Smith</lastName>
      <street1>10 TheStreet</street1>
      <city>Amsterdam</city>
      <country>NL</country>
   </billTo>
   <purchaseTotals>
      <currency>EUR</currency>
      <grandTotalAmount>20.00</grandTotalAmount>
   </purchaseTotals>
   <apPaymentType>IDL</apPaymentType>
   <apSaleService run="true">
      <cancelURL>https://www.redirect.url.html?action=cancel</cancelURL>
      <successURL>https://www.redirect.url.html?action=success</successURL>
      <failureURL>https://www.redirect.url.html?action=failure</failureURL>
   </apSaleService>
</requestMessage>
Response to a Successful Sale Service Request (
Cybersource
 Settlement Services Account)
<replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.126">
   <merchantReferenceCode>refnum1234</merchantReferenceCode>
   <requestID>4703329437356002101200</requestID>
   <decision>ACCEPT</decision>
   <reasonCode>100</reasonCode>
   <purchaseTotals>
      <currency>EUR</currency>
   </purchaseTotals>
   <apSaleReply>
      <reasonCode>100</reasonCode>
      <paymentStatus>pending</paymentStatus>
      <responseCode>00001</responseCode>
      <merchantURL>https://merchant.redirect.com/url.do?param utf=%27%22%3C%3E

      %20%E6%B8%AC%E8%A9%A6%E6%B8%AC¶m_url=https%3A%2F%2F

      www.abc.com¶m_special=+@#%~_&sign=fdaa1df42b6260a10e2e3f1c0fc</merchantURL>
      <processorTransacationID>007055</processorTransactionID>
      <reconciliationID>9530019443</reconciliationID>
      <amount>20.00</amount>
      <processorResponse>0000001</processorResponse>
      <dateTime>2020-01-11T12:47:19Z</dateTime>
   </apSaleReply>
</replyMessage>

Refund a Payment

A refund is linked to a capture or sale. Bancontact transaction support:
  • Refunds of payments that have a status of settled.
  • Partial refunds and multiple refunds.
  • Refunds for the original payment amount and the addition of 25 EUR. If the original payment amount was 45 EUR, you can refund up to 70 EUR.
The refund service request is a follow-on request that uses the request ID value returned in the sale service reply. The request ID value links the refund transaction to the original payment transaction.
Before refunding a payment and returning funds to the customer account, the payment status must be settled. You must request a refund within 180 days of the authorization.

Endpoints

Set the
apRefundService_run
 field to
true
, and send the request to one of these endpoints:
Production:
https://ics2ws.ic3.com/commerce/1.x/transactionProcessor
Test:
https://ics2wstest.ic3.com/commerce/1.x/transactionProcessor

Required Fields for Refunding a Payment

apPaymentType
Set to
IDL
.
apRefundService_refundRequestID
Include the value of the
requestID
 field that was returned in the sale service reply.
apRefundService_run
Set to
true
.
merchantID
merchantReferenceCode
purchaseTotals_currency
Set to
EUR
.
purchaseTotals_grandTotalAmount

Required Fields for
Cybersource
 Settlement Services Accounts

If you have a
Cybersource
 Settlement Services Account, include these required fields in addition to the required fields listed above.
billTo_city
billTo_country
billTo_firstName
billTo_lastName
billTo_street1

Example: Refunding a Payment

Refund Service Request
<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.126">
   <merchantID>mid43210</merchantID>
   <merchantReferenceCode>refnum1234</merchantReferenceCode>
   <purchaseTotals>
      <currency>EUR</currency>
      <grandTotalAmount>20.00</grandTotalAmount>
   </purchaseTotals>
   <apPaymentType>IDL</apPaymentType>
   <apRefundService run="true">
      <refundRequestID>4703329437356002101200</refundRequestID>
   </apRefundService>
</requestMessage>
Response to a Successful Refund Service Request
<replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.126">
   <merchantReferenceCode>refnum1234</merchantReferenceCode>
   <requestID>8484832012000483918274</requestID>
   <decision>ACCEPT</decision>
   <reasonCode>100</reasonCode>
   <purchaseTotals>
      <currency>EUR</currency>
   </purchaseTotals>
   <apRefundReply>
      <reasonCode>100</reasonCode>
      <status>refunded</status>
      <processorResponse>0000006</processorResponse>   
      <amount>20.00</amount>
      <dateTime>2020-01-11T15:43:01Z</dateTime>
      <reconciliationID>01950351</reconciliationID>
      <processorTransactionID>903344</processorTransactionID>
      <paymentStatus>completed</paymentStatus>
      <responseCode>00006</responseCode>
   </apRefundReply>
</replyMessage>

Check Transaction Status

Request the check status service when the authorization status is pending.
The check status service returns the latest status of a transaction. The request ID links the check status request to the payment or refund transaction.
  • To check the status of the sale service, include the request ID value returned in the sale service reply.
  • To check the status of the refund service, include the request ID value returned in the refund service reply.
Cybersource
 recommends waiting 30 seconds before requesting the check status service.
If the check status reply is pending, wait 5 minutes before making the check status request again. If there is still no status change, wait 20 minutes before making another check status request. After 20 minutes, the status should be
settled
,
abandoned
, or
failed
.
When the payment is confirmed, the customer is directed to your success URL. Your success URL should point to a static web page that confirms the order is being processed. When the payment completes, notify the customer using email or a dedicated web page.
Do not ship your goods until the payment status is
settled
.

Endpoints

Set the
apCheckStatusService_run
 field to
true
, and send the request to one of these endpoints:
Production:
https://ics2ws.ic3.com/commerce/1.x/transactionProcessor
Test:
https://ics2wstest.ic3.com/commerce/1.x/transactionProcessor

Required Fields for Checking Transaction Status

apCheckStatusService_checkStatusRequestID
To check the status of a sale, include the value of the
requestID
 field that was returned in the sale service reply.
apPaymentType
Set to
IDL
.
apCheckStatusService_run
Set to
true
.
merchantID
merchantReferenceCode

Example: Checking Transaction Status

Check Transaction Status Service Request
<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.126">
   <merchantID>mid43210</merchantID>
   <merchantReferenceCode>refnum1234</merchantReferenceCode>
   <apPaymentType>IDL</apPaymentType>
   <apCheckStatusService run="true">
      <checkStatusRequestID>4703329437356002101200</checkStatusRequestID>
   </apCheckStatusService>
</requestMessage>
Response to a Successful Check Transaction Status Service Request
<replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.126">
   <merchantReferenceCode>refnum1234</merchantReferenceCode>
   <requestID>52391098509302958393020294</requestID>
   <decision>ACCEPT</decision>
   <reasonCode>100</reasonCode>
   <apCheckStatusReply>
      <reasonCode>100</reasonCode>
      <reconciliationID>TC38480966</reconciliationID>
      <paymentStatus>settled</paymentStatus>
      <processorResponse>000004</processorResponse>
      <dateTime>2020-01-11T15:16:14Z</dateTime>
   </apCheckStatusReply>
</replyMessage>

Reference Information

This section contains reference information that is useful when integrating Online Bank Transfers.

Reason Codes and Response Codes for the
Simple Order
 API

Response fields and reason codes can be added at any time.
Cybersource
 recommends these best practices to ensure you keep up-to-date with the latest possible responses:
  • Parse the response data according to the field names instead of the field order in the response message. For more information about parsing response fields, see the documentation for your client.
  • Your error handler must be able to process new reason codes without problems.
  • Your error handler must use the
    decision
     field to determine the result if it receives a reason code that it does not recognize.
This table lists the possible reason codes that are returned by the
Simple Order API
 in the
reasonCode
 field. For a list of all of the possible reason codes and descriptions, see the .
Reason Codes
Reason Code
Processor Response Code
Description
100
  • 00000—status: completed.
  • 00001—status: pending.
  • 00002—status: abandoned.
  • 00003—status: authorized.
  • 00004—status: settled.
  • 00006—status: refunded.
  • 00008—status: reversed.
  • 00009—status: cancelled.
  • 00010—status: accepted.
  • 00011—status: chargeback.
  • 00012—status: settle_initiated.
  • 00013—status: settle_accepted.
  • 00014—status: refund_initiated.
  • 00015—status: active.
  • 00016—status: revoked.
  • 00017—status: expired.
  • 00020—status: refund_rejected.
The transaction was successful.
101
The request is missing one or more required fields. Examine the response fields
missingField_0
 through
missingField_N
 to identify which fields are missing. Resend the request with all the required fields.
102
  • 10000—status: failed.
One or more fields in the request contain invalid data. Examine the response fields
invalidField_0
 through
invalidField_N
 to identify which fields are invalid. Resend the request with valid data.
150
  • 20000—status: failed.
  • 20001—status: failed.
  • 20002—status: failed.
  • 30000—status: failed.
  • 30100—status: failed.
A system error caused the request to fail. You must design your transaction management system to include a way to correctly handle system errors. Depending on which payment processor is handling the transaction, the error might indicate a valid
Cybersource
 system error, or it might indicate a processor rejection because of invalid data. For either reason,
Cybersource
 recommends you to not design your system to keep resending a transaction when a system error occurs. See the documentation for the
Cybersource
 client (SDK) that you are using for important information about how to handle system errors and retries.
Other possible reasons for a failed status:
  • The signature was not included in the HTTP header.
  • The signature in the HTTP header has expired or it is not a valid signature.
151
The request was received but a server timeout occurred. This error does not include timeouts that occur 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 about handling retries in the case of system errors.
152
The request was received, but a service did not finish processing in time. 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 about handling retries in the case of system errors.
153
Your account is not enabled for the OCT service. Contact your
Cybersource
 account manager to have your account enabled for this service.
202
The payment method is expired. You might also receive this value if the expiration date that you provided does not match the date that the issuing bank has on file. Request a different form of payment.
203
  • 30000—status: failed.
  • 30100—status: failed.
  • 30200—status: failed.
  • 30400—status: failed.
  • 30500—status: failed.
The payment method was declined. No other information was provided by the issuing bank. Request a different form of payment.
204
  • 30350—status: failed.
The account does not contain sufficient funds. Request a different form of payment.
223
  • 30600—status: failed.
  • 30700—status: failed.
The processor declined the transaction due to tax errors or government compliance errors.
233
  • 30600—status: failed.
  • 30700—status: failed.
The processor declined the payment method. For more information about the decline, search for the transaction in the
Business Center
 and view the transaction details. Request a different form of payment.

Reporting

You can generate various types of reports for your financial and reconciliation data. For more information about how to automate your generated reports through API integration, see the
Reporting Developer Guide
. For more information about how to use your
Business Center
 account to generate reports, see the
Reporting User Guide
.
The
Reporting User Guide
 contains these relevant topics:
  • How and When Reports Are Generated
  • Downloading Available Reports
  • Subscribing to Standard Reports