API Reference / Mandate

Mandates

The mandate API resource can be used to acquire mandates from the customers to allow easy merchant initiated transactions in the future. When creating a mandate, a mandateId is returned. This mandateId can later be used for all kinds of actions, including sending the mandateId with a new payment request, to indicate it’s a new payment for that specific mandate.

Supported Methods

• Sepa Direct Debit
• Paypal
• Apple Pay
• Google Pay

Mandate Creation

A mandate is obtained by performing an initial mandate creation process. The creation can be achieved through a mandate create request:

The mandate creation process creates two entities: the mandate itself and a child transaction. The mandate contains the mandate Id and a reference to the child transaction (childReferenceId). The child transaction is created to gain the actual mandate.

A mandate entity can only have 1 child transaction. When the child transaction reaches a final transaction status such as success or manualintervention, the mandate will be updated with the same corresponding mandate status.

An optional amount can be added when creating a mandate and triggers the first payment of that mandate. The payment information is then used to sign the mandate. When no amount is specified, alternative ways to sign the mandate will be presented to the customer, eg. SMS, iDIN, itsme, …

Typical mandate creation flow

The general mandate creation request flow is:

1. You create a new mandate
2. Redirect the customer to the signUrl from the response.
3. The customer is invited to sign a mandate contract.
4. After the contract has been signed and stored, we redirect the customer back to the returnUrl provided in the create a new mandate.
5. You read the mandate to get the status and the mandate id.

only an active mandate can be used for payments.

Status Verification

We do not expose the status of the mandate or any of its details to the customer. It is up to you to verify the status of the mandate transaction and act accordingly. Webhooks and Notifications are provided to give you feedback, but this principle remains.

Mandate object

Example

{
 "status": "active",
 "externalMandateReference": "CCV98",
 "mandateId": "50d2f91c-9a4d-4205-b443-24ae24b316a3",
 "signed": 1622705674332,
 "type": "sepa_direct_debit",
 "merchantOrderReference": "1234678",
 "modified": 1622705674384,
 "signUrl": "https://urlToSign",
 "created": 1622705598302,
 "returnUrl": "https://google.be",
 "amount": 4.78,
 "details": {
  "customerCountry": "BEL",
  "customerLanguage": "nld",
  "customerFirstName": "Dirk",
  "customerEmail": "d.teur@ccvlab.eu",
  "sddDetails": "{\"Mndt\":{\"MndtId\":\"CCV98\",\"LclInstrm\":\"CORE\",\"Ocrncs\":{\"SeqTp\":\"RCUR\",\"Frqcy\":\"ADHO\",\"Drtn\":{\"FrDt\":\"2021-06-03\"}},\"CdtrSchmeId\":\"BE46ZZZ00000084920\",\"Cdtr\":{\"Nm\":\"CCV Belgium NV\",\"PstlAdr\":{\"AdrLine\":\"Ter Waarde 48\",\"PstCd\":\"8900\",\"TwnNm\":\"Ieper\",\"Ctry\":\"BE\"},\"Id\":\"BE0897971214\",\"CtryOfRes\":\"BE\",\"CtctDtls\":{\"EmailAdr\":\"xx\"}},\"Dbtr\":{\"Nm\":\"Dirk Teur\",\"PstlAdr\":{\"AdrLine\":\"XX\",\"PstCd\":\"3500\",\"TwnNm\":\"Hasselt\",\"Ctry\":\"BE\"},\"CtryOfRes\":\"BE\",\"CtctDtls\":{\"EmailAdr\":\"d.teur@ccvlab.eu\"}},\"DbtrAcct\":\"BE31798258915655\",\"DbtrAgt\":{\"FinInstnId\":{\"BICFI\":\"GKCCBEBB\",\"Nm\":\"BELFIUS BANK\"}},\"RfrdDoc\":\"TAR2014\",\"SplmtryData\":[{\"Key\":\"TRACKER\",\"Value\":\"53jz\"},{\"Key\":\"token\",\"Value\":\"SDD210603093318246CB87E192.1\"},{\"Key\":\"MandateName\",\"Value\":\"Mandate for direct debit terminal\"},{\"Key\":\"TemplateId\",\"Value\":330},{\"Key\":\"Terminal type\",\"Value\":null},{\"Key\":\"FirstName\",\"Value\":\"Dirk\"},{\"Key\":\"LastName\",\"Value\":\"Teur\"},{\"Key\":\"Language\",\"Value\":\"en\"},{\"Key\":\"SignerMethod#0\",\"Value\":\"mock\"},{\"Key\":\"Signer#0\",\"Value\":\"Twikey Mock Signer\"},{\"Key\":\"SignerPlace#0\",\"Value\":\"Genk\"},{\"Key\":\"SignerDate#0\",\"Value\":\"2021-06-03T07:34:28Z\"}]}}",
  "customerLastName": "Teur"
 }
}

Mandate type

Mandate status

Mandate details

For each given mandate-type, there are specific details. Besides these specific details, there are also general details that apply to all mandates.

General details

Example

{
 "customerCountry": "BEL",
 "customerLanguage": "nld",
 "customerFirstName": "Dirk",
 "customerEmail": "d.teur@ccvlab.eu",
 "customerLastName": "Teur"
}

SSD Details

Contains the raw sdd details

Example

{
"sddDetails": "{\"Mndt\":{\"MndtId\":\"CCV98\",\"LclInstrm\":\"CORE\",\"Ocrncs\":{\"SeqTp\":\"RCUR\",\"Frqcy\":\"ADHO\",\"Drtn\":{\"FrDt\":\"2021-06-03\"}},\"CdtrSchmeId\":\"BE46ZZZ00000084920\",\"Cdtr\":{\"Nm\":\"CCV Belgium NV\",\"PstlAdr\":{\"AdrLine\":\"Ter Waarde 48\",\"PstCd\":\"8900\",\"TwnNm\":\"Ieper\",\"Ctry\":\"BE\"},\"Id\":\"BE0897971214\",\"CtryOfRes\":\"BE\",\"CtctDtls\":{\"EmailAdr\":\"xx\"}},\"Dbtr\":{\"Nm\":\"Dirk Teur\",\"PstlAdr\":{\"AdrLine\":\"XX\",\"PstCd\":\"3500\",\"TwnNm\":\"Hasselt\",\"Ctry\":\"BE\"},\"CtryOfRes\":\"BE\",\"CtctDtls\":{\"EmailAdr\":\"d.teur@ccvlab.eu\"}},\"DbtrAcct\":\"BE31798258915655\",\"DbtrAgt\":{\"FinInstnId\":{\"BICFI\":\"GKCCBEBB\",\"Nm\":\"BELFIUS BANK\"}},\"RfrdDoc\":\"TAR2014\",\"SplmtryData\":[{\"Key\":\"TRACKER\",\"Value\":\"53jz\"},{\"Key\":\"token\",\"Value\":\"SDD210603093318246CB87E192.1\"},{\"Key\":\"MandateName\",\"Value\":\"Mandate for direct debit terminal\"},{\"Key\":\"TemplateId\",\"Value\":330},{\"Key\":\"Terminal type\",\"Value\":null},{\"Key\":\"FirstName\",\"Value\":\"Dirk\"},{\"Key\":\"LastName\",\"Value\":\"Teur\"},{\"Key\":\"Language\",\"Value\":\"en\"},{\"Key\":\"SignerMethod#0\",\"Value\":\"mock\"},{\"Key\":\"Signer#0\",\"Value\":\"Twikey Mock Signer\"},{\"Key\":\"SignerPlace#0\",\"Value\":\"Genk\"},{\"Key\":\"SignerDate#0\",\"Value\":\"2021-06-03T07:34:28Z\"}]}}"
}

Mandate create request

• Resource: /api/v1/mandate
• Method: POST
• Content-Type: application/json
• Authentication: basic auth
• Parameters

SDD Mandate create details

Example

{
  "details": {
   "customerLanguage": "nld",
   "customerFirstName": "Dirk",
   "customerEmail": "d.teur@ccvlab.eu",
   "customerLastName": "Teur",
   "customerCountry": "BEL",
   "customerZip": "8500",
   "customerAddress": "Spinnerijstraat 99/Bus 12",
   "customerCity": "Kortrijk"
  },
  "merchantOrderReference" : "1234678",
  "type": "SEPA_DIRECT_DEBIT",
  "returnUrl" : "https://google.be"
}

Google Pay create details

Example

{
  "type": "GOOGLEPAY",
  "returnUrl" : "https://google.be",
  "merchantOrderReference" : "1234678",
  "details": {
    "googlePayEncryptedToken": "<UNMODIFIED ENCRYPTED TOKEN HERE>"
  },
  "sequenceInfo": {
    "type": "UNSCHEDULED",
    "source": "CIT"
  }
}

Mandate create response

• Status Code: 200
• Content Type: application/json
• Content: See Mandate object

Read mandate request

This operation returns all data from a given mandate.

• Resource: /api/v1/mandate/{id}
• Method: GET
• Content-Type: application/json
• Authentication: basic auth
• Parameters: PathParam of the mandate to be fetched

Read mandate response

• Status Code: 200
• Content Type: application/json
• Content: Mandate object

Read all mandates request

This operation returns all data from all mandates.

• Resource: /api/v1/mandate
• Method: GET
• Content-Type: application/json
• Authentication: basic auth
• Parameters: Optional path parameters of page and size
  • page defaults to 0
  • size defaults to 10

Read all mandates response

• Status Code: 200
• Content Type: application/json
• Content: List of Mandate object

Read all transactions of mandate request

This operation returns all transactions initiated using the given mandate.

• Resource: /api/v1/mandate/{id}/transactions
• Method: GET
• Content-Type: application/json
• Authentication: basic auth
• Parameters: PathParam of the mandate to be fetched

Read all transactions of mandate response

• Status Code: 200
• Content Type: application/json
• Content: List of Payment object

Revoke mandate request

Used to revoke a mandate rendering it unusable. The mandate status is set to the inactive mandate status

The mandate revoke request is a simple DELETE request.

• Resource: /api/v1/mandate/{mandateId}
• Method: DELETE
• Authentication: basic auth
• URL-Parameters

Revoke mandate response

• Status Code: 200

200 if revoke is successful.

Update mandate request

• Resource: /api/v1/mandate/{mandateId}
• Method: PUT
• Content-Type: application/json
• Authentication: basic auth
• URL-Parameters

• Parameters

The details parameter is required meaning that at least one of the below specified detail-fields should be present in the update request. Otherwise, the request will return 400 - Bad Request status code.

Update general details

Updating general details can be done in combination with mandate-type specific details. There is no need to perform a separate update request to change these values. See our example in the update SDD details section below for more information.

!INFO customerFirstName & customerLastName must be updated together, otherwise the request will return a 400 - Bad Request status code.
Only provide customerEmail when it’s value has changed otherwise the request will return a 400 - Bad Request status code.

Update SDD details

!INFO customerAddress, customerCity, customerZip & customerCountry should be updated together.

Example

{
 "type": "SEPA_DIRECT_DEBIT",
 "details": {
  "customerFirstName": "Dirk",
  "customerLastName": "Teur",
  "customerEmail": "d.teur@ccvlab.eu",
  "customerLanguage": "nld",
  "customerCountry": "BEL",
  "customerZip": "5800",
  "customerCity": "Kortrijk",
  "vatNumber": "1234",
  "customerNumber": "23454",
  "customerAddress": "Zr Idastraat 15",
  "companyName": "CCV LAB",
  "customerMobilePhoneNumber": "0474144545",
  "iban": "BE68068897250734",
  "bic": "GKCCBEBB"
 }
}

Update mandate response

• Status Code: 200
• Content Type: application/json
• Content: Mandate object