Online Bank Transfers Developer Guide {#doctemp-about-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: [docs.html](https://developer.cybersource.com/docs.md "") Customer Support ---------------- For support information about any service, visit the Support Center: Recent Revisions to This Document {#doctemp-doc-revisions} ========================================================== 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](/docs/cybs/en-us/obt/developer/all/so/obt/obt-ideal-intro/obt-ideal-refund-intro/obt-ideal-refund-ex-so.md ""). Introduction to Online Bank Transfers {#doctemp-section-intro-intro} ==================================================================== 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 {#obt_intro_payment_methods_intro} ============================================================ 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. {#obt_intro_payment_methods_intro_ul_kb2_34r_mbc} Bancontact {#obt_intro_payment_methods_intro_section_o3y_l4r_mbc} ----------------------------------------------------------------- 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 {#obt_intro_payment_methods_intro_ul_ncs_dwd_mbc} iDEAL {#obt_intro_payment_methods_intro_section_p3y_l4r_mbc} ------------------------------------------------------------ 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 {#obt_intro_payment_methods_intro_ul_jbl_52p_cbc} `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 {#obt_intro_payment_methods} ===================================================== This section describes the workflows for the different Online Bank Transfer payment methods. Bancontact Workflow {#obt-intro-payment-methods-bancontact} =========================================================== This workflow describes the sequence of events that comprise a successful Bancontact transaction. ![](/content/dam/new-documentation/documentation/en-us/topics/payments-processing/altpay/obt/images/bancontact-workflow.png/jcr:content/renditions/original) 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](/docs/cybs/en-us/obt/developer/all/so/obt/obt-bancontact-intro/obt-bancontact-sale-intro.md ""). 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](/docs/cybs/en-us/obt/developer/all/so/obt/obt-bancontact-intro/obt-bancontact-status-intro.md ""). 8. `Cybersource` sends a `settled` status to the merchant. Bancontact Refund Workflow {#obt-intro-payment-methods-bancontact-flow-refund} ============================================================================== 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](/docs/cybs/en-us/obt/developer/all/so/obt/obt-bancontact-intro/obt-bancontact-refund-intro.md ""). 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](/docs/cybs/en-us/obt/developer/all/so/obt/obt-bancontact-intro/obt-bancontact-status-intro.md ""). 6. `Cybersource` sends a `refunded` status to the merchant. iDEAL Workflow {#obt-intro-payment-methods-ideal} ================================================= This workflow describes the sequence of events that comprise a successful iDEAL transaction. ![](/content/dam/new-documentation/documentation/en-us/topics/payments-processing/altpay/obt/images/ideal-workflow.png/jcr:content/renditions/original) 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](/docs/cybs/en-us/obt/developer/all/so/obt/obt-ideal-intro/obt-ideal-sale-intro.md ""). 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](/docs/cybs/en-us/obt/developer/all/so/obt/obt-ideal-intro/obt-ideal-status-intro.md ""). 8. `Cybersource` sends a `settled` status to the merchant. iDEAL Refund Workflow {#obt-intro-payment-methods-ideal-flow-refund} ==================================================================== 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](/docs/cybs/en-us/obt/developer/all/so/obt/obt-ideal-intro/obt-ideal-refund-intro.md ""). 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](/docs/cybs/en-us/obt/developer/all/so/obt/obt-ideal-intro/obt-ideal-status-intro.md ""). 6. `Cybersource` sends a `refunded` status to the merchant. Merchant Account Types {#ID-0000015f} ===================================== 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 {#klarna-intro-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 {#obt_bancontact_intro} ========================================================== 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 {#obt_bancontact_intro_ul_v22_mlj_mbc} Processing a Sale {#concept_frc_z2m_w1c} ======================================== 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 {#concept_frc_z2m_w1c_section_kxj_yzf_gbc} ---------------------------------------------------- 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`{#concept_frc_z2m_w1c_d7e266} **Test:** `https://ics2wstest.ic3.com/commerce/1.x/transactionProcessor`{#concept_frc_z2m_w1c_d7e273} Required Fields for a Sale {#obt-bancontact-sale-req-fields} ============================================================ 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 {#obt-bancontact-sale-req-fields_section_hjd_33p_2bc} -------------------------------------------------------------------------------------------------------------------- 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 : {#obt-bancontact-sale-req-fields_dl_ijd_33p_2bc} Optional Fields {#obt-bancontact-opt-fields} ============================================ item_#_productCode : item_#_productDescription : item_#_productName : item_#_quantity : item_#_unitPrice : Example: Processing a Sale {#reference_zfh_hfm_w1c} =================================================== 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> ``` {#reference_zfh_hfm_w1c_codeblock_o3r_tff_bbc} 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> ``` {#reference_zfh_hfm_w1c_codeblock_zg2_wff_bbc} 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 {#concept_dqg_yqm_w1c} ======================================= 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. {#concept_dqg_yqm_w1c_ul_ftc_l45_gbc} 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 {#concept_dqg_yqm_w1c_section_ntr_tng_gbc} ---------------------------------------------------- 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 {#reference_uln_frm_w1c} ================================================================ 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 {#reference_y2l_lrm_w1c} ===================================================== 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> ``` {#reference_y2l_lrm_w1c_codeblock_dp5_f42_bbc} 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 {#concept_bhp_34m_w1c} =============================================== 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. {#concept_bhp_34m_w1c_ul_zzt_klp_2bc} `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 {#concept_bhp_34m_w1c_section_sp4_lng_gbc} ---------------------------------------------------- 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 reasonCodeics_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](/docs/cybs/en-us/obt/developer/all/so/obt/obt-reference-intro/conref-altpay-reason-codes-so.md ""). Required Fields for Checking Transaction Status {#reference_em1_vpm_w1c} ======================================================================== 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 {#reference_ipl_hqm_w1c} ============================================================= 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> ``` {#reference_ipl_hqm_w1c_codeblock_xw5_1gf_bbc} Processing iDEAL Transactions {#obt_ideal_intro} ================================================ 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 {#obt_ideal_intro_ul_v22_mlj_mbc} Request Options {#obt_bancontact_check_refund_status} ===================================================== 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 {#obt_bancontact_check_refund_status_ul_srz_fcb_hbc} 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](/docs/cybs/en-us/obt/developer/all/so/obt/obt-ideal-intro/obt-ideal-sale-intro.md "")). 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 {#obt_bancontact_check_refund_status_section_mnm_k4g_gbc} ------------------------------------------------------------------- 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 {#obt_bancontact_check_refund_status_req_fields} ======================================================================================= apPaymentType : Set to `IDL`. apOptionsService_run : Set to `true`. merchantID : merchantReferenceCode : Example: Requesting Options {#obt_bancontact_check_refund_status_ex} ==================================================================== 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 {#concept_j4j_q2s_w1c} ======================================== 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. {#concept_j4j_q2s_w1c_dl_jf2_5lj_mbc} ` 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 {#concept_j4j_q2s_w1c_section_x5g_3qg_gbc} ---------------------------------------------------- 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`{#concept_j4j_q2s_w1c_d7e266} **Test:** `https://ics2wstest.ic3.com/commerce/1.x/transactionProcessor`{#concept_j4j_q2s_w1c_d7e273} Required Fields for a Sale {#reference_fkt_rfs_w1c} =================================================== 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 {#reference_fkt_rfs_w1c_section_hjd_33p_2bc} ----------------------------------------------------------------------------------------------------------- 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 : {#reference_fkt_rfs_w1c_dl_ijd_33p_2bc} Example: Processing a Sale {#obt_ideal_sale_ex_so} ================================================== 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> ``` {#obt_ideal_sale_ex_so_codeblock_y24_y4p_cbc} 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> ``` {#obt_ideal_sale_ex_so_codeblock_e33_bpp_cbc} 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> ``` {#obt_ideal_sale_ex_so_codeblock_zg2_wff_bbc} 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> ``` {#obt_ideal_sale_ex_so_codeblock_bmw_2pp_cbc} Refund a Payment {#obt_ideal_refund_intro} ========================================== 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. {#obt_ideal_refund_intro_ul_ftc_l45_gbc} 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 {#obt_ideal_refund_intro_section_ntr_tng_gbc} ------------------------------------------------------- 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 {#reference_sgn_qhs_w1c} ================================================================ 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 {#reference_sgn_qhs_w1c_section_hjd_33p_2bc} ----------------------------------------------------------------------------------------------------------- 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 : {#reference_sgn_qhs_w1c_dl_ijd_33p_2bc} Example: Refunding a Payment {#reference_tdz_xhs_w1c} ===================================================== 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 {#obt_ideal_status_intro} ================================================== 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. {#obt_ideal_status_intro_ul_zzt_klp_2bc} `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 {#obt_ideal_status_intro_section_sp4_lng_gbc} ------------------------------------------------------- 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 {#obt_ideal_status_req_fields} ============================================================================== 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 {#obt_ideal_status_ex_so} ============================================================== 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> ``` {#obt_ideal_status_ex_so_codeblock_ugz_npd_dbc} 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 {#concept_lc1_mps_w1c} ============================================ This section contains reference information that is useful when integrating Online Bank Transfers. Reason Codes and Response Codes for the `Simple Order` API {#conref-altpay-reason-codes-so} =========================================================================================== > 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. > {#conref-altpay-reason-codes-so_ul_qhx_r2y_p4b} > 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 for the `Simple Order` API Reference Guide](https://developer.cybersource.com/docs/cybs/en-us/reason-codes-so/reference/all/so/reason-codes-so/reason-codes-so.md "")*. | 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. {#conref-altpay-reason-codes-so_ul_lsq_h34_1rb} | 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. {#conref-altpay-reason-codes-so_ul_eln_gj4_1rb} | 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. {#conref-altpay-reason-codes-so_ul_phl_hj4_1rb} | 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. {#conref-altpay-reason-codes-so_ul_bdl_pj4_1rb} | The payment method was declined. No other information was provided by the issuing bank. Request a different form of payment. | | `204` | * 30350---status: failed. {#conref-altpay-reason-codes-so_ul_wcb_5j4_1rb} | The account does not contain sufficient funds. Request a different form of payment. | | `223` | * 30600---status: failed. * 30700---status: failed. {#conref-altpay-reason-codes-so_ul_wr2_1k4_1rb} | The processor declined the transaction due to tax errors or government compliance errors. | | `233` | * 30600---status: failed. * 30700---status: failed. {#conref-altpay-reason-codes-so_ul_t4m_kk4_1rb} | 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. | [Reason Codes] Reporting {#obt-reference-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*](https://developer.cybersource.com/docs/cybs/en-us/reporting/developer/all/rest/reporting/reporting_api.md ""). For more information about how to use your `Business Center` account to generate reports, see the [*Reporting User Guide*](https://developer.cybersource.com/library/documentation/dev_guides/reporting_and_reconciliation/Reporting_User.pdf ""). The Reporting User Guide contains these relevant topics: * How and When Reports Are Generated * Downloading Available Reports * Subscribing to Standard Reports