Create hosted mandate management
POST https://{domainname}/v1/{merchantId}/hostedmandatemanagements
Hosted Mandate Management
Using hostedMandateManagement you can create mandates through our easy to use hosted responsive pages.
Request
You can start a hostedMandateManagement flow by posting the relevant details to the endpoint. We will then return you all the details you need to redirect the consumer to us, retrieve the status and recognize the consumer when he/she returns to your website.
PayloadCreateHostedMandateManagementRequest
|
Properties
|
|||
| Property | Type | Required | Details |
|---|---|---|---|
| object | yes | read close | |
|
close
DescriptionObject containing partial information needed for the creation of the mandate. The recurrencetype, signature type of the mandate and reference to the customer are mandatory. You can also supply any personal information you already know about the customer so they have to fill in less details.
|
|||
| alias | string | no | read close |
|
close
DescriptionAn 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. |
|||
| object | depends | read close | |
|
close
DescriptionCustomer object containing customer specific inputs
|
|||
| object | depends | read close | |
| accountHolderName | string (30) | depends | read close |
|
close
DescriptionName in which the account is held.
|
|||
| iban | string (50) | depends | read close |
|
close
DescriptionThe 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.
|
|||
| companyName | string (40) | no | read close |
|
close
DescriptionName of company, as a customer
|
|||
| object | no | read close | |
|
close
DescriptionObject containing contact details like email address and phone number
|
|||
| emailAddress | string (70) | no | read close |
|
close
DescriptionEmail address of the customer
|
|||
| object | depends | read close | |
| city | string (40) | depends | read close |
|
close
DescriptionCity
|
|||
| countryCode | string (2) | depends | read close |
|
close
DescriptionISO 3166-1 alpha-2 country code
|
|||
| houseNumber | string (15) | no | read close |
|
close
DescriptionHouse number
|
|||
| street | string (50) | depends | read close |
|
close
DescriptionStreetname
|
|||
| zip | string (10) | depends | read close |
|
close
DescriptionZip code
|
|||
| object | depends | read close | |
|
close
DescriptionObject containing personal information of the customer
|
|||
| object | depends | read close | |
|
close
DescriptionObject containing the name details of the customer
|
|||
| firstName | string (15) | depends | read close |
|
close
DescriptionGiven name(s) or first name(s) of the customer
|
|||
| surname | string (70) | depends | read close |
|
close
DescriptionSurname(s) or last name(s) of the customer
|
|||
| title | enum | depends | read close |
|
close
DescriptionObject containing the title of the customer (Mr, Miss or Mrs)
|
|||
| customerReference | string (35) | yes | read close |
|
close
DescriptionThe unique identifier of a customer
|
|||
| recurrenceType | enum | yes | read close |
|
close
DescriptionSpecifies whether the mandate is for one-off or recurring payments. Possible values are:
|
|||
| signatureType | enum | yes | read close |
|
close
DescriptionSpecifies whether the mandate is unsigned or singed by SMS. Possible values are:
|
|||
| uniqueMandateReference | string | no | read close |
|
close
DescriptionThe unique identifier of the mandate
|
|||
| object | no | read close | |
|
close
DescriptionObject containing hosted mandate management specific data
|
|||
| locale | string (6) | no | read close |
|
close
DescriptionLocale to use to present the hosted mandate pages to the customer. Please make sure that a language pack is configured for the locale you are submitting. If you submit a locale that is not setup on your account we will use the default language pack for your account. You can easily upload additional language packs and set the default language pack in the Configuration Center.
|
|||
| returnUrl | string (512) | no | read close |
|
close
DescriptionThe URL that the customer is redirect to after the mandate flow has finished. You can add any number of key value pairs in the query string that, for instance help you to identify the customer when they return to your site. Please note that we will also append some additional key value pairs that will also help you with this identification process.
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. |
|||
| showResultPage | boolean | no | read close |
|
close
Description
|
|||
| variant | string | no | read close |
|
close
DescriptionThe ID of the variant used to create the Hosted Mandate Management Session in which the payment was made.
|
|||
Request example
SDK: Node.js
This scenario you will probably use the most
-
var body = { "hostedMandateManagementSpecificInput" : { "locale" : "fr_FR", "variant" : "101", "returnUrl" : "http://www.example.com" }, "createMandateInfo" : { "customerReference" : "idonthaveareference", "recurrenceType" : "RECURRING", "signatureType" : "UNSIGNED" } }; const sdkResponse = await client.v1.hostedmandatemanagements.create("merchantId", body); // sdkResponse has the following properties: // - status: the HTTP status code // - body: the response body // - isSuccess: true if the call was successful, // or false if the Worldline Global Collect platform returned an error response
Responses
For every successfully created hosted mandate management session an HTTP 201 response is returned.
Response 201 - CreatedCreateHostedMandateManagementResponse
The response contains a partialRedirectUrl. Because you can create several subdomains under which your MyCheckout payment pages will be available, you will need to add the relevant subdomain and datacenter alias that you wish to use for the transaction in front of the returned partialRedirectUrl. Next to this you also need to add the protocol (https://) in front of the whole URL. So the full redirect might be something like https://yourname.pay1.poweredbyglobalcollect.com/pay8915-53ebca407e6b4a1dbd086aad4f10354d:8915-28e5b79c889641c8ba770f1ba576c1fe:9798f4c44ac6406e8288494332d1daa0
Please note that, apart from the aforementioned, no more changes are required to the partialRedirectURL and that a GET must be used (to be sure, don't use a POST).
In the HTTP header the location is provided of the created hostedMandateManagement object so you can easily query its status, by simply performing a GET on the URI provided in this header.
|
Properties
|
|||
| Property | Type | Required | Details |
|---|---|---|---|
| RETURNMAC | string | no | read close |
|
close
DescriptionWhen the customer is returned to your site we will append this property and value to the query-string. You should store this data, so you can identify the returning customer.
|
|||
| hostedMandateManagementId | string | no | read close |
|
close
DescriptionThis is the ID under which the data for this mandate management can be retrieved.
|
|||
| partialRedirectUrl | string | no | read close |
|
close
DescriptionThe partial URL as generated by our system. You will need to add the protocol and the relevant subdomain to this URL, before redirecting your customer to this URL. A special 'payment' subdomain will always work so you can always add 'https://payment.' at the beginning of this response value to view your hosted mandate management pages.
|
|||
Response example
SDK: Node.js
This scenario you will probably use the most
-
{ "RETURNMAC" : "fecab85c-9b0e-42ee-a9d9-ebb69b0c2eb0", "hostedMandateManagementId" : "15c09dac-bf44-486a-af6b-edfd8680a166", "partialRedirectUrl" : "pay1.checkout.worldline-solutions.com/mandatemanagement/1701-8cc800ebc3b84667a0b0c9b7981d5b6a:15c09dac-bf44-486a-af6b-edfd8680a166:af6276be66bc4743abfbaa48524c59aa?requestToken=89836363-f87c-4d17-8b11-270d7d9cda9a" }
Response 400 - Bad requestErrorResponse
|
Properties
|
|||
| Property | Type | Required | Details |
|---|---|---|---|
| errorId | string | yes | read close |
|
close
DescriptionUnique reference, for debugging purposes, of this error response
|
|||
| array of object | yes | read close | |
|
close
DescriptionList of one or more errors
|
|||
| object | no | read close | |
| category | string | no | read close |
|
close
DescriptionCategory the error belongs to. The category should give an indication of the type of error you are dealing with.
Possible values:
|
|||
| code | string | yes | read close |
|
close
DescriptionError code
|
|||
| httpStatusCode | integer | no | read close |
|
close
DescriptionHTTP status code for this error that can be used to determine the type of error
|
|||
| id | string | no | read close |
|
close
DescriptionID of the error. This is a short human-readable message that briefly describes the error.
|
|||
| message | string | no | read close |
|
close
DescriptionHuman-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
DescriptionReturned 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:
|
|||
| requestId | string | no | read close |
|
close
DescriptionID of the request that can be used for debugging purposes
|
|||
Response example
SDK: Node.js
This scenario you will probably use the most
-
{ "errorId" : "15eabcd5-30b3-479b-ae03-67bb351c07e6-00000092", "errors" : [ { "code" : "20000000", "propertyName" : "bankAccountBban.accountNumber", "message" : "PARAMETER_NOT_FOUND_IN_REQUEST" } ] }