Subscription Collections
Following creation of a Subscription Plan, you may proceed to create Subscription Collections from a user, against previously created plans. After creating a collection, a URL will be provided to redirect your user to, for specifying any outstanding details, and to confirm their payment methods for collection.
Creating a Subscription Collection
Subscription Collection creation requires a client token with the subscription:collection scope. Follow the steps described in the client token guide to obtain a client token.
The GraphQL API URL https://api.stitch.money/graphql can be used for all Subscription Collection requests (whether on test or live clients).
An example of the required GraphQL mutation is shown in the below Query, with sample inputs provided in the Variables tab. The associated collection plan, user information, and reference information are specified as part of a collection creation request.
Subscription Collection Input fields
The table below details various fields that may be included in the API request:
| Name | Required | Description | Type |
|---|---|---|---|
nonce | Yes | A unique reference generated by yourself for the message and used for idempotency. | String |
contractReference | Yes | A unique reference on your system to identify the user’s subscription plan. | String |
subscriptionPlanId | Yes | The ID of the specific Subscription Plan the user is to approve the collection for. | String |
payerInformation | Yes | The information on record for the user that collection is to be made from. At a minimum, the payerId, fullName, mobileNumber and email should be populated. | Object |
expireAt | Yes | The future date and time by which the user should approve the collection. If collection is not approved by this time, the overall subscription collection will expire. | DateTime |
collectionDay | Conditional | A number for the day of the week, or a day of the month when the collection will occur, as per the frequency specified when creating the Subscription Plan, identified by the subscriptionPlanId. See the Collection Day table below for further info. This is not required when the frequency is daily. | Integer |
trial | Optional | The details of a trial period, that is specific to the user and particular collection. This overrides any trial period that is part of the Subscription Plan associated to this collection. The trial.type may be either of: - free if a free trial period is offered, the customer will not be billed for the specified period - discounted if a discount should be applied to the amount. For this value, the field trial.value should be populated to indicate the discount amount to apply/deduct. trial.period (time unit of days, weeks or months) and trial.periodValue (the number of days, weeks or months after collection for a period) should also be specified for any trial. | Object |
The collectionDay field is bound by the frequency value of the associated Subscription Plan related to the collection. Possible values per frequency are detailed below:
frequency | collectionDay |
|---|---|
weekly | From 1 = Monday, to 7 = Sunday |
monthly | From 1 to 30, or 99 = Last day of the month |
yearly | From 1 = 1 January to 365 = 31 December |
Subscription Collection Response
The response will provide a unique ID in the subscriptionCollection.id field. This ID is to be used when referencing the collection that payments have been made for, as well as for any querying or updates on a collection.
Additionally, a url will be returned, that should be used to guide the user to Stitch for their collection details completion and approval.
Handling Redirection for User Interaction
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 user to this URL, they will be guided through the process of completing the collection approval. For test clients, we
do have the following URLs 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/payment for payment requests, you'd
append the following query string to the url returned from the API: ?redirect_uri=https%3A%2F%2Fexample.com%2Fpayment.
The full URL you expose to the user should look like this
https://secure.stitch.money/connect/payment-request/2b068bd5-6a5a-42e1-8a45-673cb3ede612?redirect_uri=https%3A%2F%2Fexample.com%2Fpayment
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
Once the user completes or cancels the collection request, they'll be redirected back to the redirect_uri.
The below query string parameters will be passed back to the redirect_uri.
| Request Field | Description | Type |
|---|---|---|
id | The unique Stitch ID of this subscription collection. | ID |
status | The status of how the user engaged with the collection approval. This will have the value complete if successfully completed and approved, closed if the user clicked close in the UI, or failed if something went wrong when attempting to confirm the subscription collection details. | String |
contractReference | The value that was provided to the contractReference field when the payment request was created. This can be used as an alternative to correlate against the original subscription within your system. | String |
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:
- using the webhooks as the source of truth as they are secure and will always be sent from Stitch.
- 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 collection request if for example the request times out due to a network issue.
Using Multiple Internal Redirect URIs
For a situation where different callbacks lead to different internal URLs, you SHOULD have a single whitelisted redirect URL which can then have the logic handling the Stitch callback and redirect to the internal URLs. An overview of how to do this in NodeJS is as shown below:
const status = params.status;
switch (status) {
case "complete":
redirect("/collection-success");
case "closed":
case "failed":
redirect("/collection-retry");
default:
break;
}
Subscription Collection Statuses
The table below describes the different statuses a collection request can have, with the initial status always being SubscriptionCollectionPending:
| Status | Description |
|---|---|
SubscriptionCollectionPending | The collection request has been created, and has yet to be fully completed and approved by the user. |
SubscriptionCollectionActive | The collection request has been successfully approved by the user, and collections are in process according to the specified subscription parameters. Collection will continue indefinitely, until the collection is cancelled. |
SubscriptionCollectionCancelled | The collection request has been cancelled. Payments are no longer being collected for the given Subscription Collection. |
SubscriptionCollectionExpired | The collection request has expired and is no longer possible to complete or approve by the user. |
Subscribe to Webhooks
To receive updates, you may subscribe to webhooks using the below GraphQL mutation:
If the subscription is successfully created, the body returned by the request will look like the sample in the Example Response
tab in widget above.
For more information on receiving webhook events, listing active webhook subscriptions, unsubscribing from webhooks and validating signed webhook subscriptions, please visit the Webhooks page.
Subscription Cancellation
If you no longer need to collect payments from a user due to a subscription concluding or being cancelled by the user, a Subscription Collection may be cancelled via the Stitch API. You may either cancel all Subscription Collections for a user, or a specific Subscription Plan linked to the customer where they have multiple Subscription Plans.
The mutation to cancel a given Subscription Collection is shown below.
Subscription Payment Collections
As payments are collected by a user according to a particular Subscription Collection and associated Subscription Plan(s), you will receive updates by means of transaction webhook notifications.
The table below describes the different statuses a transaction may have:
| Status | Description |
|---|---|
TransactionPending | The collection transaction has been attempted, but is yet to be completed. Based on the paymentDue parameter specified as part of the associated Subscription Plan, payment collection will be reattempted until a final transaction success or failure is reached for the collection. |
TransactionSuccess | The collection transaction has been successfully made. |
TransactionFailure | The collection transaction failed to be made by the specified paymentDue period, relative to the time of collection. |
Together with unique Stitch IDs for each transaction, the associated subscriptionCollectionId will be provided, which may be used to associate the payment to the subscription collection.
Associated paymentMethod information will be included, confirming which method the collection occurred with.
Subscription Collections with Usage Metrics
For Collections that are associated to Subscription Plans that have the billing model usage, you may also make usage metric collection requests. This facilitates cases in which units of a product or service have been provided to the user, associated with a subscription plan, and should be billed based on the usage.
When creating usage metric requests for a particular collection, amounts will be aggregated by Stitch, until the next collection day that is applicable to tbe plan. The user will then be charged the total value of their usage for that period.
The final amount to be charged is based on the number of usage units specified. This number will be applied to the base amount initially specified as part of the collection's associated plan.
An example of the required GraphQL mutation is shown in the below Query, with sample inputs provided in the Variables tab. The id specified in the query should be the previously created and approved Subscription Collection ID.
This approach for ad-hoc collecting can only be used if the associated Subscription Plan is of the usage billing model.