On This Page

SEPA Direct Debit with Sentenial
 Developer Guide

This section describes the audience and purpose of this developer guide, its use of conventions, and links to further information.
Audience and Purpose
This guide is written for application developers who want to use APIs to integrate payment card processing with the Single Euro Payments Area (
SEPA
) service. It describes tasks that a merchant must complete in order to create and manage mandates, as well as process a direct debit, request the status of a direct debit, cancel a direct debit, or refund a direct debit. It is intended to help the merchant provide a seamless customer payment experience.
Convention
This special statement is used in this document:
An
Important
 statement contains information essential to successfully completing a task or learning a concept.
Customer Support
For support information about any service, visit the Support Center:

Recent Revisions to This Document

25.01

This revision contains only editorial changes and no technical updates.

24.01

This guide has undergone a major reorganization.
Added reporting information. See Generating Reports Using the Business Center.
Added shipping policy information. See Shipping Policy.

23.01

Updated the possible value for the
apPaymentType
 request field.

VISA Platform Connect: Specifications and Conditions for Resellers/Partners

The following are specifications and conditions that apply to a Reseller/Partner enabling its merchants through . Failure to meet any of the specifications and conditions below is subject to the liability provisions and indemnification obligations under Reseller/Partner’s contract with Visa/Cybersource.
  1. Before boarding merchants for payment processing on a VPC acquirer’s connection, Reseller/Partner and the VPC acquirer must have a contract or other legal agreement that permits Reseller/Partner to enable its merchants to process payments with the acquirer through the dedicated VPC connection and/or traditional connection with such VPC acquirer.
  2. Reseller/Partner is responsible for boarding and enabling its merchants in accordance with the terms of the contract or other legal agreement with the relevant VPC acquirer.
  3. Reseller/Partner acknowledges and agrees that all considerations and fees associated with chargebacks, interchange downgrades, settlement issues, funding delays, and other processing related activities are strictly between Reseller and the relevant VPC acquirer.
  4. Reseller/Partner acknowledges and agrees that the relevant VPC acquirer is responsible for payment processing issues, including but not limited to, transaction declines by network/issuer, decline rates, and interchange qualification, as may be agreed to or outlined in the contract or other legal agreement between Reseller/Partner and such VPC acquirer.
DISCLAIMER: NEITHER VISA NOR CYBERSOURCE WILL BE RESPONSIBLE OR LIABLE FOR ANY ERRORS OR OMISSIONS BY THE VISA PLATFORM CONNECT ACQUIRER IN PROCESSING TRANSACTIONS. NEITHER VISA NOR CYBERSOURCE WILL BE RESPONSIBLE OR LIABLE FOR RESELLER/PARTNER BOARDING MERCHANTS OR ENABLING MERCHANT PROCESSING IN VIOLATION OF THE TERMS AND CONDITIONS IMPOSED BY THE RELEVANT VISA PLATFORM CONNECT ACQUIRER.

Introduction to Direct Debits

Single Euro Payments Area (
SEPA
) is a European Union payment initiative for bank transfers denominated in euros.
SEPA
 uses the
SEPA
 scheme to make payments directly from one bank account to another, such as credits, instant credits, and direct debits. A direct debit is an instruction from a customer to their bank or building society authorizing the organization to collect varying amounts from the customer’s account, as long as the customer is given advance notice of the collection amounts and dates. The customer's consent for the payments is established by the customer agreeing to and signing a mandate.
Direct debits using
SEPA
 alternative payment services enables you to manage electronic mandates, withdraw funds from your customer’s bank account, and deposit the funds to your account.
SEPA
 direct debits are supported for one-time and recurring payments.
Direct debits are commonly used by customers to make recurring payments for debts such as credit card bills, utility bills, and monthly subscriptions. They can also be used for irregular payments such as occasional online purchases.

Supported Countries and Currency

All
SEPA
 countries are supported. The euro (
EUR
) is the supported currency.
For more information and a list of
SEPA
 countries, see:
For a list of country codes, see the .

Testing

For test transactions, send a request to the test simulator:

Terminology

For helpful descriptions of some of the terms used throughout this guide, see Terminology.

Mandate Requirements

Before processing a direct debit payment, the customer must create a mandate known as a direct debit instruction (DDI). The DDI is the method by which the customer gives the bank or service user the authority to debit the customer’s account.
The mandate must provide all the information needed for the bank or service user to collect funds from the customer. The customer must explicitly give clear authority to the bank or service user to direct debit their account.

Merchant Mandate Options

Merchants have two options for creating a mandate:
  • Create the mandate in the
    Cybersource
     system:
     the customer creates the mandate directly in the
    Cybersource
     system by sending a create mandate API request. If you choose to create the mandate this way,
    Cybersource
     manages storage of the mandate as well as submitting and updating the mandate with the
    SEPA
     scheme.
  • Create the mandate in your system:
     you create the original mandate using your own templates, in your own system. Then, you import the mandate to
    Cybersource
     by sending an import mandate API request. If you choose to create the mandate this way, you must manage all aspects of the customer’s mandate, including compliance with rules and storage.
When you create or import the customer’s mandate, you must send the customer’s information to
Cybersource
. When the mandate is created, an email is sent to the customer.

Availability and Storage

Mandate information is available in the
Cybersource
Business Center
 for 6 months after the mandate is created. You are expected to retain mandate-related information in your system until you no longer want to initiate charges for the mandate.

Expiration

The mandate ID expires after 3 years of inactivity.

Direct Debit Batching Schedule

Direct debits are settled on a batching schedule and progress through a series of stages before the transaction is complete. These are the status details for every possible direct debit status in the order in which they are likely to occur:
  1. Pending
    : the direct debit request is accepted. The payment is scheduled to be sent to the inter-bank system to initiate a debit from the customer’s account. If a customer has one or more direct debits pending, and the customer’s mandate is cancelled, all pending direct debits are also cancelled.
    Most alternative payment methods do not send a final status when a direct debit transaction completes. To retrieve the final status of a direct debit, you must request the check status service. For example, when a direct debit response is pending, you must request the check status service to recieve the final transaction status.
  2. Settle_initiated
    : the payment was sent to the inter-banking system, but funds have not been received. If a direct debit has
    settle_initiated
     status, and the customer’s mandate is cancelled, the direct debit request is processed.
  3. Settle_rejected
    : the payment request was rejected by the inter-banking system.
  4. Settle_accepted
    : the payment was accepted by the inter-bank system. If a direct debit has
    settle_accepted
     state, and the customer’s mandate is canceled, the funds are posted to your account.
  5. Settled
    : the payment is guaranteed, and you can deliver the goods. The settled status means that the payment has arrived from the customer.
  6. Returned
    : the payment was returned by the customer’s bank, at the customer’s request, within five days. This status usually follows
    Settle_accepted
     status.
  7. Refunded
    : the merchant initiated return of the customer’s payment, which typically happens after the customer returns the merchandise to the merchant.
  8. Chargeback
    : the customer asked for money back from their bank after the payment was settled, which can happen when the customer claims that the direct debit was made fraudulently.
  9. Reversed
    : the payment was canceled after it was initiated and before it could settle.

Chargebacks

During the chargeback process, banks record the valid mandate. If goods have been delivered, the bank rejects the customer’s reversal request.
When disputes are escalated, banks request proof of the mandate, which
Cybersource
 can retrieve for you. Contact your
Cybersource
 representative for assistance in retrieving the PDF of a signed mandate.
Cybersource
 recommends that you follow these guidelines:
  • Always ensure that the customer signs the mandate before you send a direct debit payment.
    Cybersource
     does not process direct debit payments using alternative payment services without the mandate ID.
  • Always verify the status of a mandate prior to initiating a direct debit payment using a direct debit request. The mandate must have
    Active
     status.
  • Communicate clearly to customers to ensure that they know about the recurring payment and how their account is charged.

Execution Date and Refund Period

The execution date of a direct debit is specified in the
paymentDetails_executionDate
 field.
When an execution date is provided, an attempt is made to process the request on the provided date. The actual execution date can vary because the
SEPA
 scheme has some non-processing dates during the year. If the execution date coincides with a non-processing date, the execution date moves to the earliest available processing date. If the execution date is moved, notification of the earliest available processing date is returned in the response.
When no execution date is provided, the next available processing date is used as the execution date.

Execution Date Rules

The execution date in a direct debit request is processed according to these
SEPA
 scheme rules:
  • The execution date is in the future and can be met, so the execution date defined in the request is used.
  • The execution date is in the future but cannot be met. For example, when the requested execution date is too close to the current date to be processed, the execution date in the request moves to the next possible execution date.
  • The execution date has already passed, so the direct debit request is rejected. To execute a payment as soon as possible, do not provide the date.

Overview of Processing Direct Debits

This section describes how to progress from one direct debits request to another in order to manage mandates and process transactions.

Create a Mandate Workflow

This workflow describes the sequence of events that comprises successfully creating a mandate.

Figure:

Create Mandate Workflow
  1. The customer chooses to sign-up for direct debits on the merchant website.
  2. The merchant sends a create mandate API request to
    Cybersource
    . For more information, see Create a Mandate.
  3. Cybersource
     responds to the merchant with a
    Pending
     status,
    SEPA
     redirect URL, and mandate ID.
  4. The merchant redirects the customer to the
    SEPA
     URL.
  5. The customer completes the sign-up for direct debits using their bank credentials and is redirected back to the merchant website.
  6. The merchant sends a check mandate status API request to
    Cybersource
     with the mandate ID. For more information, see Check a Mandate Status.
  7. Cybersource
     responds to the merchant with an
    Active
     status.
  8. The merchant displays a confirmation of the created direct debit mandate to the customer.

Update a Mandate Workflow

This workflow describes the sequence of events that comprises successfully updating a mandate.
  1. The customer chooses to sign-up for direct debits on the merchant website.
  2. The merchant sends a create mandate API request to
    Cybersource
    . For more information, see Create a Mandate.
  3. Cybersource
     responds to the merchant with a
    Pending
     status,
    SEPA
     redirect URL, and mandate ID.
  4. The merchant redirects the customer to the
    SEPA
     URL.
  5. The customer completes the sign-up for direct debits using their bank credentials and is redirected back to the merchant website.
  6. The merchant sends a check mandate status API request to
    Cybersource
     with the mandate ID. For more information, see Check a Mandate Status.
  7. Cybersource
     responds to the merchant with an
    Active
     status.
  8. The merchant displays a confirmation of the created direct debit mandate to the customer.
  9. The customer or merchant decides to update the direct debit mandate, such as updating the payment information.
  10. The merchant sends an update mandate API request to
    Cybersource
    . For more information, see Update a Mandate.
  11. Cybersource
     responds to the merchant with an
    Active
     status.
  12. The merchant displays the updated direct debit mandate confirmation to the customer.

Revoke a Mandate Workflow

This workflow describes the sequence of events that comprises successfully revoking a mandate.

Figure:

Revoke Mandate Workflow
  1. The customer chooses to sign-up for direct debits on the merchant website.
  2. The merchant sends a create mandate API request to
    Cybersource
    . For more information, see Create a Mandate.
  3. Cybersource
     responds to the merchant with a
    Pending
     status,
    SEPA
     redirect URL, and mandate ID.
  4. The merchant redirects the customer to the
    SEPA
     URL.
  5. The customer completes the sign-up for direct debits using their bank credentials and is redirected back to the merchant website.
  6. The merchant sends a check mandate status API request to
    Cybersource
     with the mandate ID. For more information, see Check a Mandate Status.
  7. Cybersource
     responds to the merchant with an
    Active
     status.
  8. The merchant displays a confirmation of the created direct debit mandate to the customer.
  9. The customer or merchant decides to cancel the direct debit mandate.
  10. The merchant sends a revoke mandate API request to
    Cybersource
    . For more information, see Revoke a Mandate.
  11. Cybersource
     responds to the merchant with a
    Revoked
     status.
  12. The merchant displays the direct debit mandate cancellation confirmation to the customer.

Import a Mandate Workflow

This workflow describes the sequence of events that comprises successfully importing a mandate.
  1. The customer signs up for direct debits on the merchant website not using the
    Cybersource
     API services.
  2. The merchant sends an import API request to
    Cybersource
    . For more information, see Import a Mandate.
  3. Cybersource
     responds to the merchant with an
    Active
     status.
  4. The merchant displays a confirmation of the created direct debit mandate to the customer.

Process a Sale Workflow

This workflow describes the sequence of events that comprises successfully processing a sale.

Figure:

Sale Workflow
  1. The customer begins to check out on the merchant website or the customer's recurring bill is due.
  2. The merchant sends a sale API request to the
    Cybersource
     with the mandate ID from the mandate creation response. For more information, see Process a Direct Debit Sale.
  3. Cybersource
     responds to the merchant with a
    pending
     status and a request ID.
  4. The merchant sends a check status API request to
    Cybersource
     with the request ID. For more information, see Check a Direct Debit Status.
  5. Cybersource
     responds to the merchant with a
    Settled
     status.
  6. The merchant displays a payment confirmation to the customer.

Cancel a Direct Debit Workflow

This workflow describes the sequence of events that comprises cancelling a mandate.

Figure:

Cancel Workflow
  1. The customer begins to check out on the merchant website or the customer's recurring bill is due.
  2. The merchant sends a sale API request to the
    Cybersource
     with the mandate ID from the mandate creation response. For more information, see Process a Direct Debit Sale.
  3. Cybersource
     responds to the merchant with a
    pending
     status and a request ID.
  4. The customer or merchant decide to cancel the payment.
  5. The merchant sends a cancel API request to
    Cybersource
     with the request ID. For more information, see Cancel a Direct Debit.
  6. Cybersource
     responds to the merchant with a
    Cancelled
     status.
  7. The merchant displays the direct debit mandate cancellation confirmation to the customer.

Reverse a Direct Debit Workflow

This workflow describes the sequence of events that comprises successfully reversing a sale.

Figure:

Reversal Workflow
  1. The customer begins to check out on the merchant website or the customer's recurring bill is due.
  2. The merchant sends a sale API request to the
    Cybersource
     with the mandate ID from the mandate creation response. For more information, see Process a Direct Debit Sale.
  3. Cybersource
     responds to the merchant with a
    pending
     status and a request ID.
  4. The merchant sends a check status API request to
    Cybersource
     with the request ID. For more information, see Check a Direct Debit Status.
  5. Cybersource
     responds to the merchant with a
    settle_initiated
     or
    settled_accepted
     status.
  6. The customer or merchant decide to cancel the payment.
  7. The merchant sends a reversal API request to
    Cybersource
     with request ID. For more information, see Reverse a Direct Debit.
  8. Cybersource
     responds with the
    Reversed
     status.
  9. The merchant displays the direct debit mandate cancellation confirmation to the customer.

Refund a Direct Debit Workflow

This workflow describes the sequence of events that comprises successfully refunding a payment.

Figure:

Refund Workflow
  1. The customer decides to return a purchase to the merchant.
  2. The merchant sends a refund API request to
    Cybersource
    . For more information, see Refund a Direct Debit.
  3. Cybersource
     responds to the merchant with a
    pending
     status.
  4. The merchant sends a check status API request to
    Cybersource
     with the refund request ID. For more information, see Check a Direct Debit Status.
  5. Cybersource
     responds to the merchant with a
    Refunded
     status.
  6. The merchant displays a refund confirmation to the customer.

Create a Mandate Statuses Workflow

This workflow describes the sequence of events that comprises successfully checking the status of a service.

Figure:

Create Mandate Status Workflow
  1. The merchant sends a create mandate API request to
    Cybersource
     and receives one of these possible statuses:
    • Failed
      : The create mandate request is not accepted.
    • Pending
      : The create mandate request is successfully processed, and the customer can sign the mandate. Send a mandate status request to retrieve status updates until the status changes. A mandate is successfully created when the status updates to
      Active
      . For more information, see Check a Mandate Status.
  2. The merchant sends a check mandate status API request to
    Cybersource
     and receives one of these possible statuses:
    • Active
      : The mandate is successfully created, updated, or imported. A direct debit can be sent for this mandate ID.
    • Expired
      : The mandate deadline has passed.
    • Failed
      : The customer was not authenticated.
    • Pending
      : The mandate is not signed yet.
    • Revoked
      : The mandate was cancelled.
  3. If the customer or merchant decides to cancel the created mandate, the merchant sends a revoke mandate API request to
    Cybersource
     and receives one of these possible statuses:
    • Failed
      : the revoke mandate request is not accepted.
    • Revoked
      : the revoke mandate request is successfully processed.
  4. If the customer or merchant decides to update the mandate, the merchant sends an update mandate API request to
    Cybersource
     and receives one of these possible statuses:
    • Active
      : the update mandate request is accepted and processed.
    • Failed
      : the update mandate request is not accepted.

Import a Mandate Statuses Workflow

This workflow describes the sequence of possible statuses you can receive when importing a mandate.

Figure:

Import Mandate Status Workflow
  1. The merchant sends an import mandate API request to
    Cybersource
     and receives one of these possible statuses:
    • Active
      : the import mandate request is accepted.
    • Failed
      : the import mandate request is not accepted.
  2. If the customer or merchant decides to cancel the created mandate, the merchant sends a revoke mandate API request to
    Cybersource
     and receives one of these possible statuses:
    • Failed
      : the revoke mandate request is not accepted.
    • Revoked
      : the revoke mandate request is successfully processed.
  3. If the customer or merchant decides to update the mandate, the merchant sends an update mandate API request to
    Cybersource
     and receives one of these possible statuses:
    • Active
      : the update mandate request is accepted and processed.
    • Failed
      : the update mandate request is not accepted.

Process a Sale Statuses Workflow

This workflow describes the sequence of possible statuses you can receive when processing a
SEPA
 transaction.

Figure:

Sale Status Workflow
  1. The merchant sends a create mandate API request to
    Cybersource
     and receives one of these possible statuses:
    • FAILED
      : The sale request is not successful. Send a new sale API request.
    • PENDING
      : The sale request is successful and is currently processing. Send a check status request until the status updates.
  2. The merchant sends a check status API request to
    Cybersource
     and receives one of these possible statuses:
    • FAILED
      : The sale request is not successful. Send a new sale API request.
    • PENDING
      : The sale request is successful and is currently processing. Send a check status request until the status updates.
    • SETTLED
      : The sale is successfully processed.
  3. If the customer or merchant decides to cancel the sale while it is pending, the merchant sends a cancel API request to
    Cybersource
     and receives one of these possible statuses:
    • CANCELLED
      : The cancel request is successful and the pending sale is cancelled.
    • FAILED
      : The sale request is not successful. Send a new cancel API request.
  4. The merchant sends a reversal API request to
    Cybersource
     and receives one of these possible statuses:
    • FAILED
      : The reversal request is not successful. Send a new reversal API request.
    • REVERSED
      : The reversal request is successful and the authorization is successfully reversed.
  5. If the customer decides to return the purchase, the merchant sends a refund API request to
    Cybersource
     and receives one of these possible statuses:
    • FAILED
      : The refund request is not successful. Send a new refund API request.
    • REFUNDED
      : The refund request is successful and the payment amount is refunded to the customer.

Requesting Direct Debits

The alternative payment direct debit services enable you to manage electronic mandates and to withdraw funds from your customer’s bank account and deposit those funds to your bank account. Direct debit services support one-time and recurring payments.
These are the direct debit services:

Create a Mandate

Create a mandate to begin processing direct debit payments. A successful create mandate response includes a pending status and a redirect URL in the
apCreateMandateReply_merchantURL
 field. Redirect the customer to the URL, which will take the customer the mandate sign-up page. In the mandate sign-up page, the customer can provide additional required information and sign the mandate.
There are four different options for creating a mandate that affect the required fields:
  • Option 1:
     Send the
    billTo_
     level fields and the
    fundTransfer_iban
     field in the API request. By including these fields, your customer does not have to enter this information when signing the mandate.
  • Option 2:
     Do not send the
    billTo_
     level fields and the
    fundTransfer_iban
     field in the API request. By not including these fields, your customer must enter this information when signing the mandate.
  • Option 3:
     Use an OBT payment to create a mandate. Include the OBT's request ID and the redirection URL in the API request.
  • Option 4
    : Create a mandate on the fly by not including the alternative payment method fields.

Redirection URLs

Cybersource
 provides three types of redirection URLs that must be included in a direct debit create mandate request. The URL to which a customer is directed is determined by the result of the mandate creation process:
Set to the URL to which the customer is redirected after the customer cancels the direct debit payment.
Set to the URL to which the customer is redirected after the direct debit payment fails.
Set to the URL to which the customer is redirected after the customer completes the direct debit payment.
If the customer chooses
cancel
, they are redirected from the mandate sign-up screen to the cancel URL. This action does not invalidate the mandate sign-up URL. The customer can use the same sign-up URL to sign the mandate later.
For example, the customer cancels during the mandate sign-up process, then later reconsiders. The mandate can still be signed. The customer can copy the mandate URL into a browser window to finish the sign-up process.

Mobile Phone Authorizations

If your process to create a mandate requires mobile phone authorization, the
customer_phone
 field is required. You can authenticate using e-mandate check box signing or an SMS-based option.
To use the mobile phone number for authorization, you must send it in the correct format:
  • Include the full international dialing code.
  • Use non-numeric characters.
For example, the UK phone number +44281234567 must be sent as
44281234567
.

Confirmation Email

To have an email sent to the customer to confirm the mandate's creation, include the optional
billTo_email
 field. The sent email includes an e-mandate PDF.

Endpoints

Set the
apCreateMandateService_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 create mandate service responds with one of these statuses in the
apCreateMandateReply_status
 field:
  • Failed
    : The create mandate request is not accepted.
  • Pending
    : The create mandate request is successfully processed, and the customer can sign the mandate. Send a mandate status request to retrieve status updates until the status changes. A mandate is successfully created when the status updates to
    Active
    . For more information, see Check a Mandate Status.
The create mandate service also responds with a reason code in the
apCreateMandateReply_reasonCode
 field. For more information about reason codes, see the Reason Codes for SEPA Direct Debits for the Simple Order API.

Create a Mandate on the Fly

A customer can sign a mandate in another system, or they might sign a paper mandate, and the details of the mandate are not in the
Cybersource
 database. When this occurs, you can create a mandate directly in the
Cybersource
 system. To do so, these requirements must be met:
  • Provide a direct debit payment.
  • Confirm you understand that the mandate is not stored with the direct debit provider and provide payment details such as account and debtor name.
  • The direct debit provider can determine that the direct debit payment is not referencing an existing mandate.
The payment details that are provided are used to create a mandate and assign it an active status, which is considered creating the mandate
on the fly
. When created, the direct debit payment is linked to the new mandate and normally processed so that any future payments referencing the mandate are handled as expected. Generating the mandate on the fly happens only for the initial payment.

Field Requirements

Creating a mandate on the fly does not require the alternative payment methods fields in the create mandate request. The alternative payment method fields are distinguished by the field beginning with
ap
.

Required Fields for Creating a Mandate

Set to the URL to which the customer is redirected after they cancel the direct debit payment.
Set to the URL to which the customer is redirected after the direct debit payment fails.
Set to
true
.
Set to the URL to which the customer is redirected after successfully completing the direct debit payment.
Set to
STS
.
Set to
sepa
.

OBT Required Field

Include this field in addition to the required fields above when creating a mandate with an OBT.
Set to the sale request ID from the OBT response.
Do not include the
fundTransfer_iban
 field if this field is present.

Optional Fields for Creating a Mandate

billTo_company
billTo_county
By not including this field, the customer must enter their email when signing the e-mandate.
By including this field, the customer receives a confirmation email that includes a copy of the e-mandate PDF.
billTo_language
billTo_middleName
By not including this field, the customer must enter their postal code when signing the e-mandate.
billTo_title
By not including this field, the customer must enter their IBAN when signing the e-mandate.

Simple Order Example: Creating a Mandate

Request 
<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.214">
    <merchantID>test-merchant</merchantID>
    <merchantReferenceCode>refnum-1234</merchantReferenceCode>
    <paymentScheme>sepa</paymentScheme>
    <billTo>
        <firstName>John</firstName>
        <lastName>Smith</lastName>
        <street1>123 Happy Ln</street1>
        <city>Sunnyville</city>
        <country>FR</country>
    </billTo>
    <apPaymentType>STS</apPaymentType>
    <apCreateMandateService run="true">
        <cancelURL>http://test.com/?cancel</cancelURL>
        <successURL>http://test.com/?success</successURL>
        <failureURL>http://test.com/?failure</failureURL>
    </apCreateMandateService>
</requestMessage>
Response to a Successful Request
<replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.214">
    <merchantReferenceCode>refnum-1234</merchantReferenceCode>
    <requestID>7103531978706248804012</requestID>
    <decision>ACCEPT</decision>
    <reasonCode>100</reasonCode>
    <requestToken>AxijrwSTgRVPOoIFpCas//9Pff2SFbAB/TDJpJl6MV/cWCTgRVPOoIFpCasAInls</requestToken>
    <apCreateMandateReply>
        <reasonCode>100</reasonCode>
        <mandateID>12345678912345</mandateID>
        <status>PENDING</status>
        <merchantURL>https://uat.nuapay.com/emandate/web/show?token=1de79ec6-XXXX-XXXX-XXXX-8569e1593438-b5gn473k58</merchantURL>
        <responseCode>00001</responseCode>
        <processorTransactionID>1ed5e676-8bbb-4852-862b-7c8cd10ae0cf</processorTransactionID>
        <dateTime>2024-03-13T18:06:39Z</dateTime>
        <dateCreated>20240313</dateCreated>
    </apCreateMandateReply>
</replyMessage>

Update a Mandate

Updating a mandate enables you to change the customer information in a pre-existing mandate. All possible variables of a customer's information that can be updated are listed in the optional fields list. See Optional Fields for Updating a Mandate.
If you receive a new IBAN for a direct debit transaction that already has a mandate, you can update the mandate instead of creating a new one.
To update a mandate, include the new IBAN in the
fundTransfer_iban
 field.
After the update mandate status becomes active, you can submit a direct debit with the same mandate ID as the original mandate.

Electronic Signature

You can also allow your customers to sign the updated mandate with an electronic signature, which requires additional fields and values. For more information, see Electronic Signature Fields.

Endpoints

Set the
apUpdateMandateService_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 update mandate service responds with one of these statuses in the
apUpdateMandateReply_status
 field:
  • Active
    : the update mandate request is accepted and processed.
  • Failed
    : the update mandate request is not accepted.
The update mandate service also responds with a reason code in the
apUpdateMandateReply_reasonCode
 field. For more information about reason codes, see the Reason Codes for SEPA Direct Debits for the Simple Order API.

Required Fields for Updating a Mandate

These are the minimum required fields to update a mandate. To update specific variables of a customer's information, use one or more fields from the optional fields list. See Optional Fields for Updating a Mandate.

Electronic Signature Fields

Include these fields in addition to the required fields if the customer is signing the updated mandate with an electronic signature.
Set to the URL to which the customer is redirected after the customer cancels the mandate update.
Set to
Y
.
Set to the URL to which the customer is redirected after the mandate update fails.
Set to the URL to which the customer is redirected after the customer completes the mandate update.

Optional Fields for Updating a Mandate

Set to
N
 if the customer is not submitting an electronic signature.
Set to
true
 if the customer is submitting an electronic signature.
billTo_company
billTo_county
billTo_language
billTo_middleName
billTo_title
fundTransfer_iban

Test Triggers for Updating a Mandate

In the
Cybersource
 test environment, you can simulate specific response messages that you receive from transaction requests by including certain values in your transaction requests. The simulated environment enables you to become familiar with the response messages and develop methods for error handling.
Your account must be configured for testing trigger values. Contact your
Cybersource
 account manager for more details.

Test Endpoint

For test transactions, send an API request to the test endpoint.
Test:
https://ics2wstest.ic3.com/commerce/1.x/transactionProcessor

Trigger Values

To test for updating a mandate, send a mandate update request, and set the
merchantReferenceCode
 field to a value listed in the Trigger Value column. The
Cybersource
 response status is returned in the
apUpdateMandateReply_status
 field.
Direct Debit Test Triggers for Updating a Mandate
Cybersource
 Response Status
Trigger Value
Active
TC85000-34
Pending
No trigger.

Simple Order Example: Updating a Mandate

Request
This example request includes optional fields to update the customer's first name, last name, and country. 
<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.214">
	<merchantID>test-merchant</merchantID>
	<merchantReferenceCode>refnum-1234</merchantReferenceCode>
	<paymentScheme>sepa</paymentScheme>
	<mandateID>12345678912345</mandateID>
	<billTo>
		<firstName>John</firstName>
		<lastName>Smith</lastName>
		<country>FR</country>	
	</billTo>
	<apPaymentType>STS</apPaymentType>
	<apUpdateMandateService run="true"/>
</requestMessage>
Response to a Successful Request
<replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.214">
	<merchantReferenceCode>refnum-1234</merchantReferenceCode>
	<requestID>5235439239636004301064</requestID>
	<decision>PENDING</decision>
	<reasonCode>100</reasonCode>
	<apUpdateMandateReply>
		<reasonCode>100</reasonCode>
		<mandateID>mandate-3829202</mandateID>
		<status>ACTIVE</status>
		<responseCode>00001</responseCode>
		<processorTransactionID>26025864-9558-487a-bf83-da960b1bacfb
                </processorTransactionID>
	</apUpdateMandateReply>
</replyMessage>

Import a Mandate

You must import a mandate to the
Cybersource
 database if you create a mandate in your own system and do not use the
Cybersource
 create mandate service.
You can import a mandate to the
Cybersource
 database in these circumstances:
  • You have existing customers with signed and active mandates
  • You manage mandates outside of
    Cybersource
When you import an existing mandate to the
Cybersource
 database, you must provide a unique value for the mandate ID in the
mandateID
 field.

Confirmation Email

To have an email sent to the customer to confirm the mandate's creation, include the optional
billTo_email
 field. The sent email includes an e-mandate PDF.

Endpoints

Set the
apImportMandateService_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 import mandate service responds with one of these statuses in the
apImportMandateReply_status
 field:
  • Active
    : the import mandate request is accepted.
  • Failed
    : the import mandate request is not accepted.
The import mandate service also responds with a reason code in the
apImportMandateReply_reasonCode
 field. For more information about reason codes, see the Reason Codes for SEPA Direct Debits for the Simple Order API.

Optional Fields for Importing a Mandate

billTo_company
billTo_county
billTo_middleName
billTo_title

Test Trigger for Importing a Mandate

In the
Cybersource
 test environment, you can simulate specific response messages that you receive from transaction requests by including certain values in your transaction requests. The simulated environment enables you to become familiar with the response messages and develop methods for error handling.
Your account must be configured for testing trigger values. Contact your
Cybersource
 account manager for more details.

Test Endpoint

For test transactions, send an API request to the test endpoint.
Test:
https://ics2wstest.ic3.com/commerce/1.x/transactionProcessor

Trigger Value

To test for importing a mandate, send a mandate import request and set the
merchantReferenceCode
 field to a value listed in the Trigger Value column. The
Cybersource
 response status is returned in the
apImportMandateReply_status
 field.
Direct Debit Test Triggers for Importing a Mandate
Cybersource
 Response Status
Trigger Value
Active
No trigger.

Simple Order Example: Importing a Mandate Service

Request
<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.214">
	<merchantID>test-merchant</merchantID>
	<merchantReferenceCode>refnum-1234</merchantReferenceCode>
	<paymentScheme>sepa</paymentScheme>
	<mandateID>12345678912345</mandateID>
	<billTo>
		<firstName>John</firstName>
		<lastName>Smith</lastName>
		<street1>321 Trafalgar Square</street1>
		<city>Sunnyville</city>
		<postalCode>55555</postalCode>
		<country>FR</country>
		<email>
test@cybs.com
</email>
		<customerID>ddd09876543212434</customerID>
	</billTo>
	<fundTransfer>
            <iban>GB82HLFX11087412413569</iban>
       </fundTransfer>
	<apPaymentType>STS</apPaymentType>
	<apImportMandateService run="true">
		<dateSigned>20240220</dateSigned>
	</apImportMandateService>
</requestMessage>
Response to a Successful Request
<replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.214">
    <merchantReferenceCode>refnum-1234</merchantReferenceCode>
    <requestID>7084683629286990803007</requestID>
    <decision>ACCEPT</decision>
    <reasonCode>100</reasonCode>
    <requestToken>Axin7wSTgA+8cJLsU/A///8ZYjWmdmnTkx5TiwnvvwyjXoA/Thk0ky9GK/uLAD6TgA+8cJLsU/A/AAAA9xPv</requestToken>
    <apImportMandateReply>
        <reasonCode>100</reasonCode>
        <mandateID>AKXEASSG5J5Z</mandateID>
        <status>ACTIVE</status>
        <responseCode>00015</responseCode>
        <processorTransactionID>b1344353-cb24-4d19-b27e-f43bc1963613</processorTransactionID>
        <dateSigned>20240220</dateSigned>
        <dateCreated>20240220</dateCreated>
        <dateTime>2024-02-20T22:32:44Z</dateTime>
    </apImportMandateReply>
</replyMessage>

Revoke a Mandate

When you revoke a mandate, any pending direct debits linked to that mandate are canceled. No notifications are sent.
When you revoke a mandate with no pending direct debits, the
SEPA
 scheme or the customer’s bank notifies you of any subsequent direct debit events.
You can no longer send a direct debit request using the mandate ID after revoking a mandate. Customer payments cannot be made against a revoked mandate.
You can revoke a mandate under these circumstances:
  • The customer requests that you revoke the mandate.
  • The customer closes their account with you.
  • Mandate information is out of date.

Endpoints

Set the
apRevokeMandateService_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 revoke mandate service responds with one of these statuses in the
apRevokeMandateReply_status
 field:
  • Failed
    : the revoke mandate request is not accepted.
  • Revoked
    : the revoke mandate request is successfully processed.
The revoke mandate service also responds with a reason code in the
apRevokeMandateReply_reasonCode
 field. For more information about reason codes, see the Reason Codes for SEPA Direct Debits for the Simple Order API.

Required Fields for Revoking a Mandate

Optional Field for Revoking a Mandate

Test Triggers for Revoking a Mandate

In the
Cybersource
 test environment, you can simulate specific response messages that you receive from transaction requests by including certain values in your transaction requests. The simulated environment enables you to become familiar with the response messages and develop methods for error handling.
Your account must be configured for testing trigger values. Contact your
Cybersource
 account manager for more details.

Test Endpoint

For test transactions, send an API request to the test endpoint.
Test:
https://ics2wstest.ic3.com/commerce/1.x/transactionProcessor

Trigger Values

To test, send a revoke mandate request, and set the
merchantReferenceCode
 field to a value listed in the Trigger Value column. The
Cybersource
 response status is returned in the
apRevokeMandateReply_status
 field.
Direct Debit Test Triggers for Revoking a Mandate
Cybersource
 Response Status
Trigger Value
Revoked
RC84100-5
Pending
No trigger.

Simple Order Example: Revoking a Mandate

Request
<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.214">
	<merchantID>test-merchant</merchantID>
	<merchantReferenceCode>refnum-1234</merchantReferenceCode>
	<paymentScheme>sepa</paymentScheme>
	<mandateID>12345678912345</mandateID>
	<apPaymentType>STS</apPaymentType>
	<apRevokeMandateService run="true"/>
</requestMessage>
Response to a Successful Request
<replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.214">
	<merchantReferenceCode>refnum-1234</merchantReferenceCode>
	<requestID>5235442454006004501064</requestID>
	<decision>ACCEPT</decision>
	<reasonCode>100</reasonCode>
	<apRevokeMandateReply>
		<reasonCode>100</reasonCode>
		<mandateID>mandate-3829202</mandateID>
		<status>REVOKED</status>
		<responseCode>00016</responseCode>
		<processorTransactionID>00142308609746028499</processorTransactionID>
		<dateSigned>20171212</dateSigned>
		<dateCreated>20171212</dateCreated>
		<dateRevoked>20190404</dateRevoked>
	</apRevokeMandateReply>
</replyMessage>

Check a Mandate Status

After the customer signs a mandate, request the check mandate status service periodically to know when the status of a pending mandate updates.
You should request a mandate check status under these circumstances:
  • The customer is redirected to one of the merchant URLs that you included in the mandate service request.
  • The customer has not returned to the merchant URL within 35 minutes of being redirected to the mandate creation page.
If you are managing your mandates using a third-party mandate management system, you cannot use
Cybersource
 to verify the status of a mandate.

Endpoints

Set the
apMandateStatusService_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 mandate status service responds with one of these statuses in the
apMandateStatusReply_status
 field:
  • Active
    : The mandate is successfully created, updated, or imported. A direct debit can be sent for this mandate ID.
  • Expired
    : The mandate deadline has passed.
  • Failed
    : The customer was not authenticated.
  • Pending
    : The mandate is not signed yet.
  • Revoked
    : The mandate was cancelled.
The check mandate status service also responds with a reason code in the
apMandateStatusReply_reasonCode
 field.
If
Cybersource
 cannot find a mandate ID in the partner system, the system responds with a
101
 error which indicates a decline error with the message
DMISSINGFIELD
. This confirms the mandate ID does not exist or is still in the process of being signed by the customer.
For more information about reason codes, see the Reason Codes for SEPA Direct Debits for the Simple Order API.

Required Fields for Checking a Mandate Status

Simple Order Example: Checking Mandate Status

Request
<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.214">
	<merchantID>test-merchant</merchantID>
	<merchantReferenceCode>refnum-1234</merchantReferenceCode>
	<paymentScheme>sepa</paymentScheme>
	<mandateID>12345678912345</mandateID>
	<apPaymentType>STS</apPaymentType>
	<apMandateStatusService run="true"/>
</requestMessage>
Response to a Successful Request
<replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.214">
	<merchantReferenceCode>test-merchant</merchantReferenceCode>
	<requestID>5235436070716004201064</requestID>
	<decision>ACCEPT</decision>
	<reasonCode>100</reasonCode>
	<apMandateStatusReply>
		<reasonCode>100</reasonCode>
		<mandateID>mandate-3829202</mandateID>
		<status>ACTIVE</status>
		<responseCode>00015</responseCode>
	</apMandateStatusReply>
</replyMessage>

Process a Direct Debit Sale

Processing a direct debit requires sending a sale request to the inter-bank system. You must include the mandate ID in the sale request. A successful sale response includes a request ID that is required for any follow-on services.
Only merchants who have a
Cybersource
 settlement services account can process a direct debit and any of the follow-on services. For more information about merchant account types, see Merchant Account Types.
A direct debit settles through a batching process. For more information, see Direct Debit Batching Schedule.

Shipping Policy

Cybersource
 recommends shipping the purchased goods after the direct debit status is settled.

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

Response Statuses

This table describes the possible statuses that you can receive in a sale response message. The status is found in the
apSaleReply_paymentStatus
 field.
Response Statuses for Processing a Direct Debit Sale
Cybersource
 Status
Description
Response Time
Chargeback
The customer claimed that the goods were not sent. The merchant can proceed with one of these actions:
  • Present the customer's mandate to their bank, prove the charge is valid, and verify that the goods were sent.
  • Charge back to the customer's account.
D +13 months
Failed
The sale request failed. The sale request was not accepted. For example, the currency provided was incorrect. Direct debits in the
SEPA
 scheme must be in British pounds sterling (
EUR
). A direct debit sent with any other currency is rejected.
Immediate in the API response.
Pending
The processor accepted the sale request, but the sale is not settled. Send a check status request for status updates. See Check a Direct Debit Status.
Immediate in API response.
Settled
The direct debit was completed, and the customer is not expected to return the goods. You can begin shipping the purchased goods.
D + 5
Settle_accepted
The
SEPA
 scheme executed the direct debit.
The customer's bank sent the funds to the merchant account.
Funds can be pulled back by the customer's bank for no reason for up to five days after the debit is executed (until D+3 days). If the funds are pulled back, the status changes to Returned.
D
Settle_initiated
The processor sent the direct debit request to the
SEPA
 scheme 1 day before the execution date (D-1 day).
Set the execution date in the sale request. If the merchant did not set the execution date, the processor sent the direct debit to the
SEPA
 scheme in the next scheduled batch. When the processor sends the direct debit, the execution date is set to the day after the batch operation.
D - 2
Settle_rejected
The
SEPA
 scheme rejected the direct debit request.
A direct debit can be rejected for several reasons, such as when the IBAN is closed or the customer has non-sufficient funds.
D - 2 to D
Returned
The direct debit is returned by the customer's bank.
D to D + 5
Reversed
The direct debit was canceled during the
settle_accepted
 status.
D to D + 5
D is the date on which the direct debit is executed.
D + is the count of business days after the execution date.
D - is the count of business days before the execution date.
The sale service also responds with a reason code in the
apSaleReply_reasonCode
 field. For more information about reason codes, see the Reason Codes for SEPA Direct Debits for the Simple Order API.

Successful Sale Batching Schedule

Direct debit sales are settled on a batching schedule and progress through a series of statuses before the transaction is complete. These are the statuses a successful sale progresses through in the order in which they occur:
  1. Pending
  2. Settle_initiate
  3. Settle_accepted
  4. Settled
For more information about the direct debit batching schedule and statuses, see Direct Debit Batching Schedule.

Required Fields for Processing a Direct Debit

Cybersource
 recommends including specific customer data fields for export compliance verifications as part of the sale service request. If a customer’s first name and last name or company name appears on any of the lists that are maintained by government agencies to support export controls, you receive information indicating that the transaction is declined. To include additional customer data, see Optional Fields for Processing a Direct Debit.
Set to
STS
.
Set to
true
.
mandateID
Set to
sepa
.
Set to
EUR
.
The value cannot exceed 11 digits and the maximum total amount cannot exceed 20 Million
EUR
.

Test Triggers for Processing Direct Debits

To test the status of a direct debit sale request, see Test Triggers for Checking Statuses.

Simple Order Example: Processing a Direct Debit

Request
<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.214">
	<merchantID>test-merchant</merchantID>
	<merchantReferenceCode>refnum-4321</merchantReferenceCode>
	<paymentScheme>sepa</paymentScheme>
	<mandateID>12345678912345</mandateID>
	<purchaseTotals>
		<currency>EUR</currency>
		<grandTotalAmount>20.00</grandTotalAmount>
	</purchaseTotals>
	<apPaymentType>STS</apPaymentType>
	<apSaleService run="true"/>
</requestMessage>
Response to a Successful Request
<replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.214">
    <merchantReferenceCode>refnum-1234</merchantReferenceCode>
    <requestID>7098276691046386503008</requestID>
    <decision>ACCEPT</decision>
    <reasonCode>100</reasonCode>
    <requestToken>AxjnrwSTgMxgsjmXDg1g//8ZYjWmdmpHhRpraKnvv3nGgmdC/oH8cMmkmXoxX9xYJOAzGCyOZcODWAAXXXXX</requestToken>
    <purchaseTotals>
        <currency>EUR</currency>
    </purchaseTotals>
    <exportReply>
        <reasonCode>100</reasonCode>
        <ipCountryConfidence>-1</ipCountryConfidence>
    </exportReply>
    <apReply>
        <transactionExpirationDate>20240313</transactionExpirationDate>
    </apReply>
    <apSaleReply>
        <reasonCode>100</reasonCode>
        <paymentStatus>pending</paymentStatus>
        <responseCode>00001</responseCode>
        <processorTransactionID>TN2ELT6W8Z3KVPG8P&</processorTransactionID>
        <reconciliationID>XFZ3YTGBFM6E</reconciliationID>
        <amount>20.00</amount>
        <processorResponse>00001</processorResponse>
        <dateTime>2024-03-07T16:07:50Z</dateTime>
    </apSaleReply>
</replyMessage>

Check a Direct Debit Status

You can verify the status of a direct debit sale or refund. Checking direct debit status requires the request ID from the sale or refund response message.
When you check the status of a sale,
Cybersource
 recommends that you request the check status service at the end of each day. The end of day is defined by Greenwich Mean Time (GMT).

Shipping Policy

Cybersource
 recommends shipping the purchased goods after the direct debit 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_status
 field:
Response Statuses for Checking Sale Status
  • Canceled
    : The customer cancelled the payment.
  • Chargeback
    : The customer asked for money back from their bank after the payment was settled.
  • Failed
    : Payment failed.
  • Pending
    : The direct debit request is accepted. The payment is scheduled to be sent to the inter-banking system to initiate a debit from the customer's account.
  • Returned
    : The customer completed a refund.
  • Reversed
    : The payment was cancelled after the sale was initiated and before the sale was settled.
  • Settle_accepted
    : The payment is accepted by the inter-banking system, and money is expected to arrive in your account within 5 days.
  • Settle_initiated
    : The payment is sent to the inter-banking system, but funds have not yet been received.
  • Settle_rejected
    : The payment was rejected by the inter-banking system.
  • Settled
    : The payment is complete, and the funds will be settled in your merchant account. You can begin shipping the purchased goods.
Response Statuses for Checking Refund Status
  • Pending
    : The refund request is accepted.
  • Refund_initiated
    : Refund request is being sent to the bank as a credit transfer.
  • Refund_rejected
    : The credit transfer request was rejected by the
    SEPA
     scheme.
  • Refunded
    : The credit transfer was successfully completed.
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 for SEPA Direct Debits for the Simple Order API.

Required Fields for Checking Direct Debit Status

Set to either the sale or refund request ID.
Set to
true
.
Set to
sepa
.
mandateID

Test Triggers for Checking Statuses

In the
Cybersource
 test environment, you can simulate specific response messages that you receive from transaction requests by including certain values in your transaction requests. The simulated environment enables you to become familiar with the response messages and develop methods for error handling.
Your account must be configured for testing trigger values. Contact your
Cybersource
 account manager for more details.

Test Endpoint

For test transactions, send an API request to the test endpoint.
Test:
https://ics2wstest.ic3.com/commerce/1.x/transactionProcessor

Trigger Values

To test, send a check status request, and set the
apCheckStatusService_reconciliationID
 field to a value listed in the Trigger Value column. The
Cybersource
 response status is returned in the
apCheckStatusReply_paymentStatus
 field.
Direct Debit Test Triggers for Checking a Direct Debit Status
Service Status Being Checked
Cybersource
 Response Status
Trigger Value
Cancellation
Settle_accepted
TC200026
Cancellation
Settle_initiated
TC200027
Refund
Refund_initiated
TC200029
Refund
Refund_rejected
TC200032
Refund
Refunded
TC200021
Refund
Settle_accepted
TC200026
Refund
Settle_initiated
TC200027
Sale
Chargeback
TC200028
Sale
Returned
TC200031
Sale
Reversed
TC200033
Sale
Settle_accepted
TC200026
Sale
Settle_initiated
TC200027
Sale
Settle_rejected
TC200030

Simple Order Example: Checking Direct Debit Status

Request
<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.214">
	<merchantID>test-merchant</merchantID>
	<merchantReferenceCode>refnum-4321</merchantReferenceCode>
	<apPaymentType>STS</apPaymentType>
	<apCheckStatusService run="true">
		<checkStatusRequestID>5235448386266004701064</checkStatusRequestID>
	</apCheckStatusService>
</requestMessage>
Response to a Successful Request
<replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.214">
    <merchantReferenceCode>refnum-1234</merchantReferenceCode>
    <requestID>7103581570376296104009</requestID>
    <decision>ACCEPT</decision>
    <reasonCode>100</reasonCode>
    <requestToken>AxjnrwSTgRX/ad56oQBJ//8ZYjWmdmpJk12DeOnvv7LpAedC/oH9MMmkmXoxX9xYJOAzGCyOZcODWAAA9Bva</requestToken>
    <apCheckStatusReply>
        <reasonCode>100</reasonCode>
        <reconciliationID>XFZ3YTIIW07G</reconciliationID>
        <paymentStatus>settle_initiated</paymentStatus>
        <processorResponse>00012</processorResponse>
    </apCheckStatusReply>
</replyMessage>

Cancel a Direct Debit

You can cancel a direct debit payment when it is in the pending status. Cancelling a direct debit requires the request ID from the sale response.

Endpoints

Set the
apCancelService_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

This table describes the possible statuses that you can receive in a cancel response message. The status is found in the
apCancelReply_status
 field.
Payment Statuses for Cancelling a Direct Debit
Cybersource
 Status
Description
Response Time
Cancelled
The cancellation request was processed successfully. The direct debit was cancelled while it was in the
Pending
 status.
Immediate in API response.
Failed
The cancellation request was not accepted. The time period for cancellation might be expired.
Immediate in API response.
The cancel service also responds with a reason code in the
apCancelReply_reasonCode
 field. For more information about reason codes, see the Reason Codes for SEPA Direct Debits for the Simple Order API.

Required Fields for Cancelling a Direct Debit

Set to
true
.
Set to the request ID from the sale response.
Set to
STS
.

Test Triggers for Cancelling a Direct Debit

In the
Cybersource
 test environment, you can simulate specific response messages that you receive from transaction requests by including certain values in your transaction requests. The simulated environment enables you to become familiar with the response messages and develop methods for error handling.
Your account must be configured for testing trigger values. Contact your
Cybersource
 account manager for more details.

Test Endpoint

For test transactions, send an API request to the test endpoint.
Test:
https://ics2wstest.ic3.com/commerce/1.x/transactionProcessor

Trigger Values

To test for cancelling a direct debit, send a cancel request and set the
apCancelService_reconciliationID
 field to a value listed in the Trigger Value column. The
Cybersource
 response status is returned in the
apCancelReply_paymentStatus
 field.
To test a check status of a cancellation request, see Test Triggers for Checking Statuses.
Direct Debit Test Triggers for Cancelling a Direct Debit
Cybersource
 Response Status
Trigger Value
Cancelled
TC200001
Pending
TC200000

Simple Order Example: Cancelling a Direct Debit

Request
<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.214">
	<merchantID>test-merchant</merchantID>
	<merchantReferenceCode>refnum-1234</merchantReferenceCode>
	<apPaymentType>STS</apPaymentType>
	<apCancelService run="true">
		<saleRequestID>5235449962346004801064</saleRequestID>
	</apCancelService>
</requestMessage>
Response to a Successful Request
<replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.214">
    <merchantReferenceCode>refnum-1234</merchantReferenceCode>
    <requestID>7103599858616262503009</requestID>
    <decision>ACCEPT</decision>
    <reasonCode>100</reasonCode>
    <requestToken>AxjnrwSTgRZAYu0pZKph//8ZYjWmdmpJk12EVgnvv7M5jedC/oH9MMmkmXoxX9xYJOBFkAAoyjyQSMAAgv/Z</requestToken>
    <apCancelReply>
        <reasonCode>100</reasonCode>
        <status>CANCELLED</status>
        <processorResponse>00009</processorResponse>
        <dateTime>2024-03-13T19:59:47Z</dateTime>
        <paymentStatus>cancelled</paymentStatus>
        <responseCode>00009</responseCode>
        <reconciliationID>XFZ3YTIIW0E0</reconciliationID>
    </apCancelReply>
</replyMessage>

Reverse a Direct Debit

You can reverse a direct debit before it is processed by the customer’s bank. The direct debit must be in the
settle_initiated
 or
settle_accepted
 status. To reverse a
pending
 direct debit, send a cancel direct debit request instead. See Cancel a Direct Debit.
To reverse a direct debit after more than five days, or when the status is
settled
, send a refund request instead. See Refund a Direct Debit.

Endpoints

Set the
apCancelService_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 reversal service responds with one of these statuses in the
apCancelReply_status
 field:
  • Accepted
    : The cancellation request is being processed and
    Cybersource
     is trying to reverse the debit request with the inter-bank system.
  • Failed
    : The original direct debit request is rejected by the customer's bank. A reversal is not necessary.
  • Reversed
    : The direct debit was canceled during the
    settle_accepted
     status.
The reversal service also responds with a reason code in the
apCancelReply_reasonCode
 field. For more information about reason codes, see the Reason Codes for SEPA Direct Debits for the Simple Order API.

Required Fields for Reversing a Direct Debit

Set to
true
.
Set to the request ID from the sale response.
Set to
STS
.

Optional Field for Reversing a Direct Debit

Simple Order Example: Reversing a Direct Debit

Request
<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.214">
	<merchantID>test-merchant</merchantID>
	<merchantReferenceCode>refnum-1234</merchantReferenceCode>
	<apPaymentType>STS</apPaymentType>
	<apCancelService run="true">
		<saleRequestID>5235449962346004801064</saleRequestID>
	</apCancelService>
</requestMessage>
Response to a Successful Request
<replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.214">
	<merchantReferenceCode>refnum-1234</merchantReferenceCode>
	<requestID>5235453358716005001064</requestID>
	<decision>ACCEPT</decision>
	<reasonCode>100</reasonCode>
	<apCancelReply>
		<reasonCode>100</reasonCode>
		<status>REVERSED</status>
		<processorResponse>00009</processorResponse>
		<paymentStatus>cancelled</paymentStatus>
		<responseCode>00009</responseCode>
		<reconciliationID>V1J11FUUWJNL</reconciliationID>
	</apCancelReply>
</replyMessage>

Refund a Direct Debit

You can refund a direct debit either for a partial amount or the entire amount of the payment. The direct debit must be in
Settled
 or
Settled_accepted
 status before you can send a refund request.

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

Response Statuses

This table describes the possible statuses you can receive in a refund response message. The status is found in the
apRefundReply_status
 field.
Payment Statuses for the Refund Service
Status
Description
Response Time
Pending
The refund request was accepted by the
Cybersource
 partner and is sent to the scheme. Send a check status request for status updates. See Check a Direct Debit Status.
Immediate in API response.
Failed
The refund request was not accepted.
Immediate in API response.
Refund_initiated
The refund request was sent to the scheme in a batch.
D
Refunded
The customer's account received the refund.
D + 1
Refund_rejected
The scheme rejected the refund request. A refund can be rejected for several reasons, such as when a customer closes the account that was used for paying the merchant.
D + 1
D is the date on which the direct debit is executed.
D + is the count of business days after the execution date.
The refund service also responds with a reason code in the
apRefundReply_reasonCode
 field. For more information about reason codes, see the Reason Codes for SEPA Direct Debits for the Simple Order API.

Required Fields for Refunding a Direct Debit

Test Triggers for Refunds

To test the status of a direct debit refund request, see Test Triggers for Checking Statuses.

Simple Order Example: Refunding a Direct Debit

Request
<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.214">
	<merchantID>test-merchant</merchantID>
	<merchantReferenceCode>refnum-1234</merchantReferenceCode>
	<purchaseTotals>
		<currency>EUR</currency>
		<grandTotalAmount>20</grandTotalAmount>
	</purchaseTotals>
	<apPaymentType>STS</apPaymentType>
	<apRefundService run="true">
		<refundRequestID>5235448386266004701064</refundRequestID>
	</apRefundService>
</requestMessage>
Response to a Successful Request
<replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.214">
	<merchantReferenceCode>DEF56789</merchantReferenceCode>
	<requestID>5591931695706359004012</requestID>
	<decision>ACCEPT</decision>
	<reasonCode>100</reasonCode>
	<purchaseTotals>
		<currency>EUR</currency>
	</purchaseTotals>
	<apRefundReply>
		<reasonCode>100</reasonCode>
		<transactionID>szl-3cd0789c-8180-4b7f-ba5c-ba83f286768e</transactionID>
		<status>PENDING</status>
		<processorResponse>00001</processorResponse>
		<amount>20.00</amount>
		<dateTime>2019-05-30T05:12:54Z</dateTime>
		<reconciliationID>XFZ3ZVTDFCM5</reconciliationID>
		<returnRef>XFZ3YVOEOX63</returnRef>
		<paymentStatus>pending</paymentStatus>
		<responseCode>00001</responseCode>
	</apRefundReply>
</replyMessage>

Reference Information

This section contains reference information that is useful when integrating
SEPA
 Direct Debits.

Merchant Account Types

There are three types of
Cybersource
 merchant accounts:
  • Cybersource
     Settlement Services Account
  • Commercial Bureau Account
  • Processor Direct Contract Account
For more information about each account type, contact your
Cybersource
 sales representative.

Cybersource
 Settlement Services Accounts

Cybersource
 settlement services accounts have 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
 request the export compliance service for every transaction using the
Cybersource
 settlement services account. The export compliance service compares customer information to an export control list 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 send these authorization fields in your sale service request:
billTo_city
billTo_country
billTo_firstName
billTo_lastName
billTo_street1
If you do not send these fields, you might not see errors in the
Cybersource
 test environment, but you will see errors in the production environment.

Commercial Bureau Accounts

Commercial bureau accounts are for merchants who have their own mandate management system, and a pre-existing service user number (SUN). These accounts must use the payment processor selected by
Cybersource
. The selected payment processor acts as a technical service provider (TSP) to process payments. Funds are credited to the account linked to the SUN by the
SEPA
 scheme.

Processor Direct Contract Accounts

Processor direct contract accounts must use the payment provider selected by
Cybersource
. If you have existing direct contracts, you must inform your sales representative.

Reason Codes for
SEPA
 Direct Debits 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.

Export Compliance Reason Codes

This table describes the reason codes from the response message for transactions that require US export compliance checking.
For more information about export compliance, see the .
Export Compliance Reason Codes
Reason Code
Description
Returned Field
100
Customer's order was successfully processed. No export restrictions.
exportReply
700
The customer is on a list issued by a government agency containing entities with whom trade is restricted.
Possible action: Reject the customer's order.
exportReply
701
One or both of these events occurred:
  • A government agency maintains an embargo against the country indicated in the billing or shipping address.
  • You supplied an export list for one of more of the offers in the order, but the shipping country submitted by the order is not in that list.
    Possible action: Reject the customer's order.
exportReply
702
A government agency maintains an embargo against the country associated with the email address.
Possible action: Reject the customer's order.
exportReply
703
A government agency maintains an embargo against the country associated with the IP address.
Possible action: Reject the customer's order.
exportReply

Generating Reports Using the
Business Center

You can generate various types of reports for your financial and reconciliation data. For more information about how to automate your reports, 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

Additional Resources

For additional information about how to use the
Business Center
 and work with reports, see these helpful resources.
Business Center
 Navigation
For an overview of the various resources available in the
Business Center
, see this YouTube video:
Getting Started with the
Business Center
For a step-by-step demonstration of how to navigate in the
Business Center
, see this YouTube video:
Managing Report Subscriptions
For an overview of how to manage report subscriptions in the Downloadable Reports section in the
Business Center
, see this YouTube video:
Downloading Reports
For an overview of how to download available reports in the Reports section in the
Business Center
, see this YouTube video:

Terminology

This table defines the terms used throughout this guide.
Terminology
Term
Description
BBAN
Basic Bank Account Number. Every country can have its own standards for format and length. This can vary by country and can include up to four parts:
  • Bank account number
  • Bank code
  • Branch code
  • Check digits
BIC
Bank Identifier Code.
DDI
Direct debit instruction. An instruction given from an account holder to the bank, which authorizes a company to withdraw variable amounts of money at unscheduled times, purchase by purchase. Direct debits are among the most common financial transactions in the world.
EDD
European Direct Debit.
FSP
Financial settlement partner. The
Cybersource
 account that collects funds on your behalf and settles the funds to your merchant account.
IBAN
International bank account number. This number consists of three parts:
  • Basic bank account number (BBAN)
  • Checking account digits
  • Country code
Mandate
Authorization from a customer to a business giving the business permission to withdraw funds from the customer's account. Mandates are issued in paper or electronic format.
OBT
Online Bank Transfer.
For more information, see the Online Bank Transfers Developer Guide.
OTP
One-time password. An authentication method using a unique password that can be used only once.
SEPA
Single Euro Payments Area. European Union payment initiative for bank transfers denominated in euros.
SEPA scheme
Functionality defined by SEPA for transferring funds. SEPA defines three SEPA schemes: credit, instant credit, and direct debit.
SWIFT
Society for Worldwide InterBank Financial Telecommunication.
TSP
Technical service provider. A processor that processes payments for
Cybersource
.