On This Page

Bacs UK Direct Debit for Alternative Payment Processing
 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 Bacs Payment Schemes Limited (
Bacs
) 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

Bacs
 Payment Schemes Limited (
Bacs
) is an electronic system used in the UK to make payments directly from one bank account to another. 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
Bacs
 alternative payment services enables you to manage electronic mandates, withdraw funds from your customer’s bank account, and deposit the funds to your account.
Bacs
 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 Country and Currency

Bacs
 direct debits are supported in the UK. The supported currency is the British pound sterling (
GBP
).

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.
When the customer creates a mandate with you, they enter their basic bank account number (BBAN) on the mandate signing page. In the UK, the customer’s BBAN is 8 digits, and the branch identifier is 6 digits, for a total of 14 digits.

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
    Bacs
     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.

Handling Mandates Passed Through Third-Party Systems

Some
Cybersource
 merchants require the ability to manage their mandates in a third-party system. In these cases, you can pass a direct debit payment that references one of these third-party mandates. However, the third-party mandate must be lodged with the
Bacs
 scheme and be in an active status. If these conditions are met,
Cybersource
 dynamically creates a reference to the mandate and links your payment to it.
Cybersource
 recommends that merchants use both mandate and payment services from a single payment service provider.

Bacs
 Payment Processing Requirements

Follow these guidelines to process a
Bacs
 payment request using a mandate created in a third-party system:
  • The mandate must be created using a pre-existing service user number (SUN).
  • The mandate must be passed to
    Bacs
     in an active state.
Details of the mandate from the third-party system must be passed:
  • Reference the unique mandate identifier.
  • Provide the debtor account details.
  • Include the customer’s first and last name.

Migrating a Mandate to
Cybersource

You must meet these requirements in order to migrate a third-party mandate to
Cybersource
:
  • You must have an existing service user number (SUN).
  • The third-party mandate must be created in another system.
  • When it is passed, the mandate must be in active status.
The third-party mandate is passed into the
Bacs
 system by the Automated Direct Debit Instruction Service (AUDDIS). Details of the third-party mandate are passed to
Cybersource
 in the common transaction processing (CTP) sale API request.
When the mandate is migrated to
Cybersource
, the mandate is created in
Cybersource
 only once.
Cybersource
 stores the mandate details so that payments made against the third-party mandate in future transactions are automatically matched.

Third-Party Mandate Updates

If the mandate managed by a third party is amended after it is migrated to
Cybersource
, the change of information about the mandate must be communicated to the payment service provider so that the mandates are synchronized. This information is provided by the Automated Direct Debit Amendment and Cancellation Service (ADDACS).

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.
    Bacs
     has no time limit for the customer to receive the chargeback.
  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
Bacs
 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
Bacs
 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.

Refund Period

In the
Bacs
 scheme, there is no time limit for refunds. A customer can request a refund at any time after the original settlement date.
Cybersource
 keeps active customer data for up to 6 months past a transaction settlement date. If a customer requests a refund more than 6 months past the settlement date,
Cybersource
 must manually match the customer data to the transaction and might not be able to make the match.

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,
    Bacs
     redirect URL, and mandate ID.
  4. The merchant redirects the customer to the
    Bacs
     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,
    Bacs
     redirect URL, and mandate ID.
  4. The merchant redirects the customer to the
    Bacs
     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,
    Bacs
     redirect URL, and mandate ID.
  4. The merchant redirects the customer to the
    Bacs
     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.

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
Bacs
 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. 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.
In the
Bacs
 scheme, when a mandate is created, it automatically has active status. Direct debit collections can be made against it immediately. To process a direct debit payment, see Process a Direct Debit Sale.

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 Bacs Direct Debits for the Simple Order API.

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
STL
.
Set to
UK
.
Set to
bacs
.

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 may have to enter their BBAN when signing the e-mandate.
By not including this field, the customer must enter their IBAN when signing the e-mandate.

Test Triggers for Creating 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 create mandate 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 Creating a Mandate
Cybersource
 Response Status
Trigger Value
Pending
Any value except
TC86000-1
.
Failed
TC86000-1

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>bacs</paymentScheme>
    <billTo>
        <firstName>John</firstName>
        <lastName>Smith</lastName>
        <street1>123 Happy Ln</street1>
        <city>Sunnyville</city>
        <country>UK</country>
    </billTo>
    <apPaymentType>STL</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.
Updates to existing mandates are limited to this information:
To make any other changes to a mandate, you must revoke the existing mandate and create a new mandate with the new information. See Revoke a Mandate.
After the update mandate status becomes active, you can submit a direct debit with the same mandate ID as the original mandate.

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 Bacs 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.

Optional Fields for Updating a Mandate

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, send an update mandate 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
Pending
Any value except
TC86000-1
Failed
TC86000-1

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>bacs</paymentScheme>
	<mandateID>12345678912345</mandateID>
	<billTo>
		<firstName>John</firstName>
		<lastName>Smith</lastName>
		<country>UK</country>	
	</billTo>
	<apPaymentType>STL</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 Bacs Direct Debits for the Simple Order API.

Optional Fields for Importing a Mandate

Test Trigger
s
 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 Values

To test, send an import mandate 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 Importing a Mandate
Cybersource
 Response Status
Trigger Value
Active
Any value except
TC84100-1
Failed
TC84100-1

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>bacs</paymentScheme>
	<mandateID>12345678912345</mandateID>
	<billTo>
		<firstName>John</firstName>
		<lastName>Smith</lastName>
		<street1>321 Trafalgar Square</street1>
		<city>Sunnyville</city>
		<postalCode>55555</postalCode>
		<country>UK</country>
		<email>
test@cybs.com
</email>
		<customerID>ddd09876543212434</customerID>
	</billTo>
	<fundTransfer>
            <iban>GB82HLFX11087412413569</iban>
       </fundTransfer>
	<apPaymentType>STL</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
Bacs
 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 Bacs 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
Any value except
TC84100-13
Failed
TC84100-13

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>bacs</paymentScheme>
	<mandateID>12345678912345</mandateID>
	<apPaymentType>STL</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
150
 error which indicates a general system failure. The mandate ID might not exist or is still in the signature flow process if it is a new mandate.
For more information about reason codes, see the Reason Codes for Bacs 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>bacs</paymentScheme>
	<mandateID>12345678912345</mandateID>
	<apPaymentType>STL</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.
Any time after the purchase is settled.
Failed
The sale request failed. The sale request was not accepted. For example, the currency provided was incorrect. Direct debits in the
Bacs
 scheme must be in British pounds sterling (
GBP
). 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 + 3
Settle_accepted
The
Bacs
 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
Bacs
 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
Bacs
 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 - 3
Settle_rejected
The
Bacs
 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.
Invalid for
Bacs
.
Returned
The direct debit is returned by the customer's bank.
D to D + 3
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 Bacs 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

Set to
STL
.
Set to
true
.
mandateID
Set to
bacs
.
Set to
GBP
.
The value cannot exceed 11 digits and the maximum total amount cannot exceed 20 Million
GBP
.

Test Triggers for Processing Direct Debits

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 sale request and set the
purchaseTotals_grandTotalAmount
 field to a value listed in the Trigger Value column. The
Cybersource
 response status is returned in the
apSaleReply_paymentStatus
 field.
Direct Debit Test Triggers for Processing Direct Debits
Cybersource
 Response Status
Trigger Value
Failed
4000.01
Pending
Any value except
4000.01

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>bacs</paymentScheme>
	<mandateID>12345678912345</mandateID>
	<purchaseTotals>
		<currency>GBP</currency>
		<grandTotalAmount>20.00</grandTotalAmount>
	</purchaseTotals>
	<apPaymentType>STL</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>GBP</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
    Bacs
     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 Bacs 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
bacs
.
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 Statuses
Cybersource
 Response Status
Trigger Value
Chargeback
TC200028
Failed
TC200010
Pending
TC200000
Refunded
TC200021
Refund-initiated
TC200029
Refund-rejected
TC200032
Settle-accepted
TC200026
Settled
Any value that is not used in the triggers for testing other statuses.
Settled-initiated
TC200027
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>STL</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 has the
Pending
 status or the
Settle_initiated
 status. The status of the direct debit payment determines the cancel status message. 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
Accepted
The cancellation request is accepted and sent to the scheme to reverse the direct debit. This status is returned when the direct debit is canceled after the status of the sale has changed from
Pending
 to
Settle_initiated
.
Immediate in API response.
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 Bacs 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
STL
.

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, 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_status
 field.
Direct Debit Test Triggers for Cancellations
Cybersource
 Response Status
Trigger Value
Cancelled
Any value except
TC400000
Failed
TC400000

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>STL</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>

Refund a Direct Debit

You can refund a direct debit only for the entire amount of the payment. The direct debit must have
Settled
 or
Settled_accepted
 status before you can send a refund request.

Refund Period

In the
Bacs
 scheme, there is no time limit for refunds. A customer can request a refund at any time after the original settlement date.
Cybersource
 keeps active customer data for up to 6 months past a transaction settlement date. If a customer requests a refund more than 6 months past the settlement date,
Cybersource
 must manually match the customer data to the transaction and might not be able to make the match.

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
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
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 Bacs Direct Debits for the Simple Order API.

Required Fields for Refunding a Direct Debit

Set to
STL
.
Set to the request ID from the sale response.
Set to
true
.
Set to
bacs
.
Set to
GBP
.
Value cannot exceed 11 digits. Total amount maximum is 20 Million
GBP
.

Test Triggers for Refunds

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 refund request and set the
purchaseTotals_grandTotalAmount
 field to a value listed in the Trigger Value column. The
Cybersource
 response status is returned in the
apRefundReply_status
 field.
Direct Debit Triggers for Refunds
Cybersource
 Response Status
Trigger Value
Failed
2000.07
Pending
2000.00
Refunded
Any value that is not used in the triggers for testing other 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>GBP</currency>
		<grandTotalAmount>20</grandTotalAmount>
	</purchaseTotals>
	<apPaymentType>STL</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>GBP</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
Bacs
 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
Bacs
 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
Bacs
 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
ADDACS
Automated Direct Debit Amendment and Cancellation Service. An automated service used by banks that tracks cancellations and amendments made to the DDI.
AUDDIS
Automated Direct Debit Instruction Service. The
Bacs
 service that enables your organization to set up new direct debit instructions (DDIs) electronically at your customer's bank.
Bacs
Bacs
 Payment Schemes Limited. An electronic system used to make payments and apply credits directly from one bank account to another in the United Kingdom.
Bacs
 scheme
Functionality defined by
Bacs
 for transferring funds in the United Kingdom.
Bacs
 defines two schemes: direct debit and direct credit.
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.
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.
SUN
Service user number. A unique identifier issued to the merchant by your sponsor bank on behalf of the
Bacs
 direct debit scheme.
SWIFT
Society for Worldwide InterBank Financial Telecommunication.
TSP
Technical service provider. A processor that processes payments for
Cybersource
.