Skip to main content

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.

Mandate Creation Fields

The table below describes the fields detailed in the above mutation. Details about the CustomerInput and CollectionInput types can be seen by exploring the variables in the above request.

NameDescriptionType
accountTrackingIndicates 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
accountTypeOnly "current" (cheque) or "savings" accounts are supported.String
contractReferenceThe 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
collectionFrequencyIndicates 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
collectionDayA 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
debitValueTypeThe debicheck type determining possible values for the instalmentAmount. This can be either "fixed", "variable" or "usage-based". "fixed" requires a fixed, specific amount as indicated by the instalment amount. "variable" requires a changeable amount for instalmentAmount. "usage-based" is variable with an upper limit of R500 000.00. The upper limit for "fixed" and "variable" is 1.5x the instalment amountString
instalmentAmountThe 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
amountAdjustmentFrequencyThe 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
adjustmentAmountThe value that the instalment amount can be adjusted by. This can be a negative value.Number
adjustmentRateThe rate by which the instalmentAmount can be adjusted by.Number
firstCollectionAmountAn initial colleciton amount that will be different from the recurring collection amount. Only collected once.Number
firstCollectionDateThe 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.

CollectionFrequency and CollectionDay

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

CollectionFrequencyCollectionDay
weekly1 = Monday to 7 = Sunday
fortnightly1 = Monday to 7 = Sunday (first week).
8 = Monday to 14 = Sunday (second week).
monthly1 - 30
quarterly1 - 30, or 99 = last day
biAnnually1 - 30, or 99 = last day
adHoc1 = the last Monday to 6 = last Saturday.
7 = first Monday to 12 = first Saturday.
14 = 2nd last day.
99 = last day.
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.

Surface URL and Handle Callback

The URL returned by the API requires that a whitelisted redirect_uri 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:

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

https://secure.stitch.money/recurring-payment/2b068bd5-6a5a-42e1-8a45-673cb3ede612?
redirect_uri=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 redirect_uri 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 redirect_uri. The below query string parameters will be passed back to the redirect_uri.

Request FieldDescriptionType
idThe unique id of this mandate creation request.ID
statusStatus 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 requestString

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

StatusDescription
RecurringPaymentConsentPendingThe initial status of a mandate creation request after creation via the API. This indicates that authorisation of the mandate is pending.
RecurringPaymentConsentProcessingThis indicates that the customer did not respond to the mandate authorisation request so an RMS mandate has been created and is in a processing stage. Once this mandate is successful, the status will move to RecurringPaymentConsentGranted.
RecurringPaymentConsentGrantedThe 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.
RecurringPaymentConsentRevokedThe mandate was revoked and cannot be collected against. The revocation will explicitly be carried out by you via API

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. You will need to explicitly opt in to RMS mandates.

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