DebiCheck Integration Process

Mandate Creation

A mandate is the contract that indicates an authorised agreement between you and your customer. When creating a mandate, you will be required to provide detailed mandate information about the customer and the subscription. Your customer will be prompted to authorise the mandate as per the provided details. Once a mandate is successfully authorised, you will receive a mandate token to be used to initiate fund collection.

The below diagram depicts mandate creation via the Stitch API. The outcome of the mandate creation is a mandate token to invoke future collections against. The mandate token will be accompanied by a status, indicating whether you will be able to collect against the mandate or not.

sequenceDiagram participant Client participant Customer participant Stitch API Client->>+Stitch API: create mandate Stitch API->>Stitch API: validate input alt is valid Stitch API-->>-Client: redirectUri Client->>+Customer: redirectUri Customer->>+Customer: redirectUri invoked Customer->>+Stitch API: confirm mandate details and authorise mandate Stitch API->>Stitch API: initiate mandate via provider Stitch API-->>-Customer: authorise mandate via bank MFA prompt Customer->>+Stitch API: mandate actioned Stitch API->>Stitch API: update mandate status Stitch API-->>Client: return mandate token and status else is not valid Stitch API-->>-Client: validation error end

Create a Mandate

A mandate can be created using the below mutation. Mandate creation is protected by a client token. You'll need to follow the steps described in the client token guide to obtain a client token with the client_recurringpaymentconsentrequest scope.

To create a mandate, information about the customer and information about the collection, including type and frequency, is required. A redirect_uri will be returned for you surface to your customer, allowing them to provide any outstanding details and to authorise the mandate.

Open in IDE ↗

Mandate Creation Fields

The table below describes the fields detailed in the above mutation. Details about the DebicheckCollectionInput,DebicheckPayerBankInformationInput and PayerInformationInput types can be seen by exploring the variables in the above request.

Name	Description	Type
accountTracking	Indicates whether account tracking is enabled for the mandate. Account tracking is the ability for the customer's account to be tracked for up to 10 days. As soon as money comes into the account, the collection will be resubmitted.	Boolean
accountType	Only "current" (cheque) or "savings" accounts are supported.	String
contractReference	The contract number for the customer. This will appear on the customer's statement and must be unique per mandate creation request with a maximum of 14 characters.	String
collectionFrequency	Indicates how often the collection should occur. This can be "weekly", "fortnightly", "monthly", "quarterly", "biannually", "yearly", "adHoc". The collectionFrequency determines the possible values for collectionDay. More details can be found below.	String
collectionDay	A number for the day of the week, or a day of the month when the collection will occur, as per the frequency specified in the collectionFrequency field.	Number
debitValueType	The debicheck type determining possible values for the instalmentAmount. This can be either "fixed", "variable" or "usageBased". "fixed" requires a fixed, specific amount as indicated by the instalment amount. "variable" and "usageBased" require a changeable amount for instalmentAmount. The upper limit for "fixed" and "variable" is 1.5x the instalment amount as provided in the maximumCollectionAmount field. "usageBased" is variable with an upper limit of R500 000.00.	String
instalmentAmount	The currency value in rands, to be collected from the customer at the frequency stipulated. This is required if the debitValueType is "fixed" or "variable" and can be optionally supplied for "usage-based".	Number
maximumCollectionAmount	The maximum value in rands, that can be collected from the customer at the frequency stipulated. This is up to 1.5x the instalmentAmount in the case of "fixed" and "variable" mandates and R500 000.00 for "usageBased". This value will default to the upper limits if not provided.	Number
amountAdjustmentFrequency	The frequency at which adjustment of the instalment amount can occur. Values can either be "never", "quarterly","biannually",annually", "repo". If this is "never" or "repo", adjustmentAmount and adjustmentRate can be omitted.	String
adjustmentAmount	The value that the instalment amount can be adjusted by. This can be a negative value.	Number
adjustmentRate	The rate by which the instalmentAmount can be adjusted by.	Number
firstCollectionAmount	An initial colleciton amount that will be different from the recurring collection amount. Only collected once.	Number
firstCollectionDate	The date that the collection of the firstCollectionAmount should take place. Occurs a single time. Provided in ISO 8601 format i.e. "2024-04-04"	String

Note

• For the "Identifying Document" you can specify either a South African Identity Document, a Passport Number or a Temporary Residence ID.
• The phoneNumber supplied must be a South African phone number without the country code.
• The amount is an amount in rands i.e. 10.00.
• Either adjustmentAmount or adjustmentRate should be supplied if the adjustmentFrequency is supplied.
• fullName is the customer's name and surname with a maximum of 35 characters.

FirstCollectionDate and FirstCollectionAmount

• These values represent an initial amount to be collected from your customers. These values do not correspond with the specified collectionDay and collectionFrequency values and are a once-off collection.
• If provided, both of these values are required
• firstCollectionDate should be at least 4 days in the future from the current day, including the current day.

CollectionFrequency and CollectionDay

The collectionDay field is bound by the collectionFrequency value provided. The possible values per collectionFrequency are detailed below.

CollectionFrequency	CollectionDay
weekly	1 = Monday to 7 = Sunday
fortnightly	1 = Monday to 7 = Sunday (first week). 8 = Monday to 14 = Sunday (second week).
monthly	1 - 30, or 99 = last day
quarterly	1 - 30, or 99 = last day
biAnnually	1 - 30, or 99 = last day
yearly	1 - 30, or 99 = last day
adHoc	1 = the last Monday to 6 = last Saturday. 7 = first Monday to 12 = first Saturday. 14 = 2nd last day. 99 = last day.

1 - 30, or 99 = last day

• "1 - 30, or 99 = last day" represent the days in a month.
• In the case of quarterly, biAnnually,yearly, the term begins from the date of the first collection.

Surface URL and Handle Callback

The URL returned by the API requires that a whitelisted returnUrl is appended to it as a query string argument. If you direct a customer to this URL, they will be guided through the process of authorising the mandate. For test clients, the following URLs are whitelisted by default:

• https://localhost:8080
• https://localhost:8080/return
• https://localhost:3000
• https://localhost:3000/return
• https://localhost:9000
• https://localhost:9000/return

For example, if your whitelist URL configuration included the URL https://example.com/subscription, you'd append the following query parameter to the url returned from the API: &returnUrl=https%3A%2F%2Fexample.com%2Fsubscription. The full URL you expose to the customer should look like this

https://secure.stitch.money/v2/consent?requestId=2b068bd5-6a5a-42e1-8a45-673cb3ede612&clientId=test-195944A9-E957-4532-B574-D37BD5FD9297&
    returnUrl=https%3A%2F%2Fexample.com%2Fpayment

Whitelisting Redirect URLs

To add or remove a URL from the whitelist, please reach out to a Stitch Engineer via our Support Form

Please note that production clients will not be allowed to use unsecure returnUrl params such as http. For example

http://example.com/subscription ❌

https://example.com/subscription ✅

Once the customer completes or cancels the mandate creation request, they'll be redirected back to the returnUrl. The below query string parameters will be passed back to the redirect_uri.

Request Field	Description	Type
id	The unique id of this mandate creation request.	ID
status	Status will have the value complete if successful, closed if the customer clicked close in the UI, or failed if something went wrong when attempting the mandate creation request	String

The id can be used to retrieve the final mandate creation request status and other details from the Stitch API, as well as relate to incoming webhooks.

danger

The status field should not be used for any database operations since an external party can tweak it. To secure yourself from attackers who can send a fake payload to your redirect or webhook endpoint, we recommend:

1. using the webhooks as the source of truth as they are secure and will always be sent from Stitch.
2. making use of signed webhooks since you'll be able to verify the signature of each incoming webhook's request payload.

Using the webhooks also ensures you'll still be able to know the final status of a mandate creation request if for example the request times out due to a network issue.

Mandate Creation Status

Mandate status updates are obtained via a subscription to the webhooks. At different stages in its lifecycle, the mandate can have the following statuses

Status	Description
PaymentConsentPending	The initial status of a mandate creation request after creation via the API. This indicates that authorisation of the mandate is pending.
PaymentConsentProcessing	This indicates that mandate has moved from pending and is currently being processed. This would happen in a case where a customer did not respond to the mandate authorisation request so an RMS mandate has been created and is in a processing stage. Additionally, this would happen when a delayed mandate is created. Once the mandate has been successfully processed, the status will move to PaymentConsentGranted.
PaymentConsentGranted	The debicheck mandate was authorised and can be collected against. In the case of RMS, this indicates that the RMS mandate was created and can be collected against.
PaymentConsentCancelled	The debicheck mandate has been cancelled before it was authorised. This is in-flight cancellation, triggered by you via API.
PaymentConsentExpired	The debicheck mandate has expired before it was authorised. This is triggered by a pre-set expiry for the mandate initiation request.
PaymentConsentRevoked	The mandate was revoked and cannot be collected against. The revocation will explicitly be carried out by you via API or internally due to an operation resulting in collection not being permitted i.e. disputes.

Registered Mandate Service (RMS) Mandates

DebiCheck authenticated mandates rely on customer involvement to authorise the mandate, creating a verified agreement between you and them. In a case where customers have failed to authenticate a mandate, Stitch will create an RMS mandate with the customer. The RMS mandate does not require customer authorisation and will serve as a regular debit order, allowing for collections based on the terms provided in the mandate request.

note

RMS mandates are regular electronic debit orders and thus, are disputable given that an authorised agreement does not exist between you and the customer

Delayed Mandates

Debicheck mandate initiation requests can only be processed within a banking window of 03h00 - 19h00 each day. To ensure that your customers are still able to sign up for debicheck during this period, a delayed mandate will be created and submitted to the bank during the next available processing window. Your customer will receive the MFA prompt for authorisation once the delayed mandate has been submitted for processing.