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

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 Request
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 Response
{
"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.

Last updated on