Create a Mandate

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

Light Dark
Request 
123456789101112131415161718
<="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>
</>
Response to a Successful Request
1234567891011121314151617
<: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>
</>