Create mandate

POST https://{domainname}/v1/{merchantId}/mandates

Mandates

The mandates REST services allow you to manage mandates, used in SEPA Direct Debit payments.

Request

Creates a mandate to be used in a SEPA Direct Debit payment.

Create mandate supports idempotent requests

PayloadCreateMandateRequest

Property	Type	Required	Details
Properties Expand all properties Hide deprecated properties
alias	string	no	read close
close Description An alias for the mandate. This can be used to visually represent the mandate. Do not include any unobfuscated sensitive data in the alias. Default value if not provided is the obfuscated IBAN of the customer.
customer	object	no	read close
close Description Customer object containing customer specific inputs SDK Object type MandateCustomer
bankAccountIban	object	depends	read close
close Description Object containing IBAN information Depends on: Required for Create mandate and Create payment calls SDK Object type BankAccountIban
accountHolderName	string (30)	depends	read close
close Description Name in which the account is held. Depends on: Required for the creation of a Payout Required for Create and Update token calls.
iban	string (50)	depends	read close
close Description The IBAN is the International Bank Account Number. It is an internationally agreed format for the BBAN and includes the ISO country code and two check digits. Depends on: Required for the creation of a Payout Required for Create and Update token. Required for payments with product 9000 (AfterPay Installments) in Austria (AT) and Germany (DE). Required for Create mandate and Create payment with mandate calls
companyName	string (40)	no	read close
close Description Name of company, as a customer
contactDetails	object	no	read close
close Description Object containing contact details like email address and phone number SDK Object type MandateContactDetails
emailAddress	string (70)	no	read close
close Description Email address of the customer
mandateAddress	object	depends	read close
close Description Object containing billing address details Depends on: Required for Create mandate and Create payment calls. Required for Create hostedCheckout calls where the IBAN is also provided. SDK Object type MandateAddress
city	string (40)	depends	read close
close Description City Depends on: Required for Create mandate and Create payment calls. Required for Create hostedCheckout calls where the IBAN is also provided.
countryCode	string (2)	depends	read close
close Description ISO 3166-1 alpha-2 country code Depends on: Required for Create mandate and Create payment calls. Required for Create hostedCheckout calls where the IBAN is also provided.
houseNumber	string (15)	no	read close
close Description House number
street	string (50)	depends	read close
close Description Streetname Depends on: Required for Create mandate and Create payment calls. Required for Create hostedCheckout calls where the IBAN is also provided.
zip	string (10)	depends	read close
close Description Zip code Depends on: Required for Create mandate and Create payment calls. Required for Create hostedCheckout calls where the IBAN is also provided.
personalInformation	object	depends	read close
close Description Object containing personal information of the customer Depends on: Required for Create mandate and Create payment calls SDK Object type MandatePersonalInformation
name	object	depends	read close
close Description Object containing the name details of the customer Depends on: Required for create mandate and Create payment calls SDK Object type MandatePersonalName
firstName	string (15)	depends	read close
close Description Given name(s) or first name(s) of the customer Depends on: Required for create mandate and Create payment calls
surname	string (70)	depends	read close
close Description Surname(s) or last name(s) of the customer Depends on: Required for create mandate and Create payment calls
title	enum	depends	read close
close Description Object containing the title of the customer (Mr, Miss or Mrs) Depends on: Required for create mandate and Create payment calls
customerReference	string (35)	yes	read close
close Description The unique identifier of a customer
language	string	no	read close
close Description The language code of the customer, one of de, en, es, fr, it, nl, si, sk, sv.
recurrenceType	enum	yes	read close
close Description Specifies whether the mandate is for one-off or recurring payments. Possible values are: UNIQUE RECURRING
returnUrl	string	depends	read close
close Description Return url to use if the mandate signing requires redirection. Note: The provided URL should be absolute and contain the https:// protocol. IP addresses are not supported, neither localhost. For use on mobile devices a custom protocol can be used in the form of protocol://. This protocol must be registered on the device first. URLs without a protocol will be rejected. Depends on: Required when the signatureType is 'SMS'
signatureType	enum	yes	read close
close Description Specifies whether the mandate is unsigned or singed by SMS. Possible values are: UNSIGNED SMS
uniqueMandateReference	string	no	read close
close Description The unique identifier of the mandate

Request example

SDK: Ruby

This scenario you will probably use the most

bank_account_iban = Domain::BankAccountIban.new
bank_account_iban.iban = 'DE46720200700359736690'

contact_details = Domain::MandateContactDetails.new
contact_details.email_address = 'wile.e.coyote@acmelabs.com'

mandate_address = Domain::MandateAddress.new
mandate_address.city = 'Monumentenvallei'
mandate_address.country_code = 'NL'
mandate_address.street = 'Woestijnweg'
mandate_address.zip = '1337XD'

name = Domain::MandatePersonalName.new
name.first_name = 'Wile'
name.surname = 'Coyote'

personal_information = Domain::MandatePersonalInformation.new
personal_information.name = name
personal_information.title = 'Miss'

customer = Domain::MandateCustomer.new
customer.bank_account_iban = bank_account_iban
customer.company_name = 'Acme labs'
customer.contact_details = contact_details
customer.mandate_address = mandate_address
customer.personal_information = personal_information

body = Domain::CreateMandateRequest.new
body.customer = customer
body.customer_reference = 'idonthaveareference'
body.language = 'nl'
body.recurrence_type = 'UNIQUE'
body.signature_type = 'UNSIGNED'

response = client.v1.merchant('merchantId').mandates.create(body)

Responses

Please find below an overview of the possible responses.

Response 201 - CreatedCreateMandateResponse

The create mandate request succeeded. Data on the resulting mandate can be found in the response.

Property	Type	Required	Details
Properties Expand all properties Hide deprecated properties
mandate	object	no	read close
close Description Object containing information on a mandate SDK Object type MandateResponse
alias	string	no	read close
close Description An alias for the mandate. This can be used to visually represent the mandate. Do not include any unobfuscated sensitive data in the alias. Default value if not provided is the obfuscated IBAN of the customer.
customer	object	no	read close
close Description Customer object containing customer specific inputs SDK Object type MandateCustomer
bankAccountIban	object	depends	read close
close Description Object containing IBAN information Depends on: Required for Create mandate and Create payment calls SDK Object type BankAccountIban
accountHolderName	string (30)	depends	read close
close Description Name in which the account is held. Depends on: Required for the creation of a Payout Required for Create and Update token calls.
iban	string (50)	depends	read close
close Description The IBAN is the International Bank Account Number. It is an internationally agreed format for the BBAN and includes the ISO country code and two check digits. Depends on: Required for the creation of a Payout Required for Create and Update token. Required for payments with product 9000 (AfterPay Installments) in Austria (AT) and Germany (DE). Required for Create mandate and Create payment with mandate calls
companyName	string (40)	no	read close
close Description Name of company, as a customer
contactDetails	object	no	read close
close Description Object containing contact details like email address and phone number SDK Object type MandateContactDetails
emailAddress	string (70)	no	read close
close Description Email address of the customer
mandateAddress	object	depends	read close
close Description Object containing billing address details Depends on: Required for Create mandate and Create payment calls. Required for Create hostedCheckout calls where the IBAN is also provided. SDK Object type MandateAddress
city	string (40)	depends	read close
close Description City Depends on: Required for Create mandate and Create payment calls. Required for Create hostedCheckout calls where the IBAN is also provided.
countryCode	string (2)	depends	read close
close Description ISO 3166-1 alpha-2 country code Depends on: Required for Create mandate and Create payment calls. Required for Create hostedCheckout calls where the IBAN is also provided.
houseNumber	string (15)	no	read close
close Description House number
street	string (50)	depends	read close
close Description Streetname Depends on: Required for Create mandate and Create payment calls. Required for Create hostedCheckout calls where the IBAN is also provided.
zip	string (10)	depends	read close
close Description Zip code Depends on: Required for Create mandate and Create payment calls. Required for Create hostedCheckout calls where the IBAN is also provided.
personalInformation	object	depends	read close
close Description Object containing personal information of the customer Depends on: Required for Create mandate and Create payment calls SDK Object type MandatePersonalInformation
name	object	depends	read close
close Description Object containing the name details of the customer Depends on: Required for create mandate and Create payment calls SDK Object type MandatePersonalName
firstName	string (15)	depends	read close
close Description Given name(s) or first name(s) of the customer Depends on: Required for create mandate and Create payment calls
surname	string (70)	depends	read close
close Description Surname(s) or last name(s) of the customer Depends on: Required for create mandate and Create payment calls
title	enum	depends	read close
close Description Object containing the title of the customer (Mr, Miss or Mrs) Depends on: Required for create mandate and Create payment calls
customerReference	string (35)	yes	read close
close Description The unique identifier of the customer to which this mandate is applicable
recurrenceType	enum	yes	read close
close Description Specifieds whether the mandate is for one-off or recurring payments.
status	enum	no	read close
close Description The status of the mandate. Possible values are: ACTIVE EXPIRED CREATED REVOKED WAITING_FOR_REFERENCE BLOCKED USED
uniqueMandateReference	string	no	read close
close Description The unique identifier of the mandate
merchantAction	object	no	read close
close Description Object that contains the action, including the needed data, that you should perform next, showing the redirect to a third party to complete the payment or like showing instructions SDK Object type MandateMerchantAction
actionType	enum	no	read close
close Description Action merchants needs to take in the online mandate process. Possible values are: REDIRECT - The customer needs to be redirected using the details found in redirectData
redirectData	object	no	read close
close Description Object containing all data needed to redirect the customer SDK Object type MandateRedirectData
RETURNMAC	string	no	read close
close Description A Message Authentication Code (MAC) is used to authenticate the redirection back to merchant after the payment.
redirectURL	string	no	read close
close Description The URL that the customer should be redirected to. Be sure to redirect using the GET method.

Response example

SDK: Ruby

This scenario you will probably use the most

{
    "mandate" : {
        "customerReference" : "idonthaveareference",
        "customer" : {
            "bankAccountIban" : {
                "iban" : "DE46720200700359736690"
            },
            "mandateAddress" : {
                "street" : "Woestijnweg",
                "city" : "Monumentenvallei",
                "zip" : "1337XD",
                "countryCode" : "NL"
            },
            "companyName" : "Acme labs",
            "contactDetails" : {
                "emailAddress" : "wile.e.coyote@acmelabs.com"
            },
            "personalInformation" : {
                "name" : {
                    "firstName" : "Wile",
                    "surname" : "Coyote"
                },
                "title" : "Miss"
            }
        },
        "recurrenceType" : "UNIQUE",
        "status" : "ACTIVE",
        "uniqueMandateReference" : "42268d8067df43e18a50a2ebf4bdb729"
    }
}

Response 400 - Bad requestErrorResponse

Property	Type	Required	Details
Properties Expand all properties Hide deprecated properties
errorId	string	yes	read close
close Description Unique reference, for debugging purposes, of this error response
errors	array of object	yes	read close
close Description List of one or more errors
items	object	no	read close
close Description Contains detailed information on one single error. SDK Object type APIError
category	string	no	read close
close Description Category the error belongs to. The category should give an indication of the type of error you are dealing with. Possible values: CONNECT_PLATFORM_ERROR - indicating that a functional error has occurred in the Connect platform. PAYMENT_PLATFORM_ERROR - indicating that a functional error has occurred in the Payment platform. IO_ERROR - indicating that a technical error has occurred within the Connect platform or between Connect and any of the payment platforms or third party systems.
code	string	yes	read close
close Description Error code
httpStatusCode	integer	no	read close
close Description HTTP status code for this error that can be used to determine the type of error
id	string	no	read close
close Description ID of the error. This is a short human-readable message that briefly describes the error.
message	string	no	read close
close Description Human-readable error message that is not meant to be relayed to customer as it might tip off people who are trying to commit fraud
propertyName	string	no	read close
close Description Returned only if the error relates to a value that was missing or incorrect. Contains a location path to the value as a JSonata query. Some common examples: a.b selects the value of property b of root property a, a[1] selects the first element of the array in root property a, a[b='some value'] selects all elements of the array in root property a that have a property b with value 'some value'.
requestId	string	no	read close
close Description ID of the request that can be used for debugging purposes

Response example

SDK: Ruby

This scenario you will probably use the most

{
    "errorId" : "15eabcd5-30b3-479b-ae03-67bb351c07e6-00000092",
    "errors" : [
        {
            "code" : "20000000",
            "propertyName" : "customer.billingAddress.street",
            "message" : "PARAMETER_NOT_FOUND_IN_REQUEST"
        }
    ]
}

Create mandate

Mandates

Request

PayloadCreateMandateRequest

Description

Description

Description

Depends on:

Description

Depends on:

Description

Depends on:

Description

Description

Description

Description

Depends on:

Description

Depends on:

Description

Depends on:

Description

Description

Depends on:

Description

Depends on:

Description

Depends on:

Description

Depends on:

Description

Depends on:

Description

Depends on:

Description

Depends on:

Description

Description

Description

Description

Depends on:

Description

Description

Request example

Responses

Response 201 - CreatedCreateMandateResponse

Description

Description

Description

Description

Depends on:

Description

Depends on:

Description

Depends on:

Description

Description

Description

Description

Depends on:

Description

Depends on:

Description

Depends on:

Description

Description

Depends on:

Description

Depends on:

Description

Depends on:

Description

Depends on:

Description

Depends on:

Description

Depends on:

Description

Depends on:

Description