Processing iDEAL Transactions

On This Page
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

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

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

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

Light Dark
Request Options
1234567
<="urn:schemas-cybersource-com:transaction-data-1.158">
    <merchantID>abcd_1234</merchantID>
    <merchantReferenceCode>refnum1234</merchantReferenceCode>
    <apPaymentType>IDL</apPaymentType>
    <apOptionsService run="true"/>
    </apOptionsService>
</>
Response to a Successful Options Request
12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061
<: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>
</>
Light Dark
Sale Service Request
1234567891011121314151617
<="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>
</>
Response to a Successful Sale Service Request
12345678910111213141516171819202122
<: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%ACm_url=https%3A%2F%2F

      www.abc.comm_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>
</>
Sale Service Request (
Cybersource
 Settlement Services Account)
123456789101112131415161718192021222324
<="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>
</>
Response to a Successful Sale Service Request (
Cybersource
 Settlement Services Account)
12345678910111213141516171819202122
<: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%ACm_url=https%3A%2F%2F

      www.abc.comm_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>
</>
Light Dark
Refund Service Request
123456789101112
<="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>
</>
Response to a Successful Refund Service Request
1234567891011121314151617181920
<: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>
</>
Light Dark
Check Transaction Status Service Request
12345678
<="urn:schemas-cybersource-com:transaction-data-1.126">
   <merchantID>mid43210</merchantID>
   <merchantReferenceCode>refnum1234</merchantReferenceCode>
   <apPaymentType>IDL</apPaymentType>
   <apCheckStatusService run="true">
      <checkStatusRequestID>4703329437356002101200</checkStatusRequestID>
   </apCheckStatusService>
</>
Response to a Successful Check Transaction Status Service Request
12345678910111213
<: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>
</>