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

Light Dark
Request 
123456789101112131415161718
<="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>
</>
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>
</>