Create a Mandate

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

Redirection URLs

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

Mobile Phone Authorizations

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

Confirmation Email

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

Endpoints

Set the
apCreateMandateService_run
 field to
true
, and send the request to one of these endpoints:
Production:
https://ics2ws.ic3.com/commerce/1.x/transactionProcessor
Test:
https://ics2wstest.ic3.com/commerce/1.x/transactionProcessor

Response Statuses

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