Skip to main content

Mandate Reference API

POST/rest/create_mandate_reference

The Mandate Reference API is used to create SEPA mandate references before a payment is submitted. SEPA Direct Debit payments can either provide the mandate reference directly in the Payment API via sepa_mandate, or create it upfront with this endpoint.

This endpoint is used with SEPA Direct Debit for both schemes: dd (B2C) and dd_b2b (B2B).

The same endpoint also creates MB WAY mandates (payment_type: "mbway"), which work differently. See the section below.

Mandate Reference API Parameters​

payment_typeStringrequired
Use dd for the SEPA Direct Debit B2C scheme or dd_b2b for the SEPA Direct Debit B2B scheme
recurringInteger
Set to 1 for a recurring mandate. Omit for a one-time mandate
first_nameString
Customer's first name
last_nameString
Customer's last name
emailString
Customer's email address
addressString
Street address
address2String
Second address line
cityString
City of the customer
postal_codeString
Postal code of the customer
stateString
State or region of the customer
countryString
Country code in ISO 3166-1 alpha-2
phoneString
Customer's phone number
account_holderString
Bank account holder's name
ibanString
IBAN of the bank account
bicString
BIC of the bank account
Example RequestHTTP
POST /rest/create_mandate_reference
Authorization: Basic <base64(api_key:api_password)>
Content-Type: application/json
{
"payment_type": "dd",
"recurring": 1,
"first_name": "Max",
"last_name": "Mustermann",
"account_holder": "Max Mustermann",
"iban": "DE89370400440532013000"
}

Mandate Reference API Response​

transaction_idString
ID of the created transaction. For recurring SEPA payments, use it later as original_transaction_id
tokenString
Mandate reference token to display to the customer and store for later use as sepa_mandate
status_codeInteger
Status code of the transaction. A successful mandate reference is returned as 9 (registered)
statusString
Status of the transaction
error_codeInteger
Error code for the response
order_idString
Order ID of the transaction when available
Example ResponseJSON
{
"transaction_id": "c2a6bf6d-2dd7-4a9c-b4de-2d04347d802b",
"token": "a7678918bfbbfa449cf9ff78446b60a4",
"status_code": 9,
"status": "registered",
"error_code": 0,
"order_id": "123000"
}

Typical Flow​

  1. Create a mandate reference with POST /rest/create_mandate_reference.
  2. Show the returned token (mandate reference) to the customer as part of the SEPA mandate text.
  3. Store the returned transaction_id.
  4. Create the actual SEPA payment with the Payment API.
  5. For recurring collections, use the stored transaction_id as original_transaction_id.
note

If you already have your own mandate reference, you can skip this endpoint and send it directly as sepa_mandate in the Payment API.

MB WAY mandates​

With payment_type: "mbway", this endpoint creates an MB WAY mandate. The customer receives an approval request in the MB WAY app and sets a monthly amount limit and an expiry date there. After approval, you can charge the mandate with recurring payments that need no further approval.

The sections above describe SEPA mandate references and still apply to dd and dd_b2b unchanged. For mbway the differences are:

  • The request must be authenticated with Basic authentication or a checksum. An unauthenticated request is rejected with HTTP 401.
  • phone is required: the mobile number linked to the customer's MB WAY account. Bank account parameters are not used.
  • The mandate is returned as pending (2), not registered (9). It becomes registered when the customer approves it, and you receive a postback.
  • token is empty in the response. Use the returned transaction_id as original_transaction_id when you charge the mandate.
payment_typeStringrequired
mbway
phoneStringrequired
Mobile number linked to the customer's MB WAY account: the customer's mobile number in international format (+4917143214321, 0049 171 43214321), or a Portuguese one without country code (912345678). It is converted to the MB WAY format <country code>#<number> automatically; numbers already in that format (34#612345678) are accepted too. Other values are rejected with error code 166
first_nameString
Customer's first name, shown to the customer in the MB WAY app
last_nameString
Customer's last name
postback_urlStringrequired
The URL where updates about the mandate status are posted
Example Request (MB WAY)HTTP
POST /rest/create_mandate_reference
Authorization: Basic <base64(api_key:api_password)>
Content-Type: application/json
{
"payment_type": "mbway",
"phone": "912345678",
"first_name": "Maria",
"last_name": "Silva",
"postback_url": "https://your-postback.url.com"
}
transaction_idString
ID of the mandate. Use it as original_transaction_id for recurring charges
status_codeInteger
2 (pending) until the customer approves the mandate, then 9 (registered)
mbway_mandate_statusString
State of the mandate in MB WAY: pending, active, suspended, expired or cancelled
mbway_mandate_amount_limitString
Monthly limit set by the customer: the total that can be charged on the mandate per month. Included once the mandate is approved
mbway_mandate_expires_onString
Date (YYYY-MM-DD) until which the mandate can be charged. Included once the mandate is approved
Example Response (MB WAY)JSON
{
"transaction_id": "1f7b2c4d-93a8-4b6e-a3f0-5d2e8c9b7a61",
"payment_type": "mbway",
"status_code": 2,
"status": "pending",
"message": "Waiting for the customer to approve the MB WAY mandate.",
"mbway_mandate_status": "pending",
"token": null,
"error_code": 0
}

Typical Flow (MB WAY)​

  1. Create the mandate with POST /rest/create_mandate_reference and payment_type: "mbway".
  2. Store the returned transaction_id. Tell the customer to approve the mandate in the MB WAY app.
  3. Wait for the postback with status_code 9 and mbway_mandate_status active.
  4. Charge the mandate with the Payment API, recurring: 1 and original_transaction_id set to the stored transaction_id.

A charge is rejected with error code 162 (not an MB WAY mandate), 163 (not approved yet), 164 (suspended, cancelled or expired) or 165 (above the monthly limit). See MB WAY mandates for the full lifecycle.

Last updated on