Skip to main content

Batch API Collections

The Batch API comprises a set of Stitch API GraphQL mutations used for creating, modifying and submitting batches for processing recurring payments using tokenised credentials stored in Vault. Use the GraphQL API URL https://api.stitch.money/graphql for test and live client requests.

Batch Creation

The clientCollectionBatchCreate mutation is used to create a batch with specified number of payment collections. Populate a CollectionInput object in the input collections array field with a provisioned card token to be charged.

An errors field is returned containing a list of invalid collections. Use the nonce associated with each error to identify the invalid collection, and the code to determine the reason.

Collection Limits

A maximum of 20000 collections can be included in a clientCollectionBatchCreate request. Use the clientCollectionBatchAdd mutation to add additional collections to a batch for processing.

Errors

The table below describes the error codes returned for invalid payment collections submitted in a request.

CodeDescription
invalid_payment_methodThe card payment method information is invalid or incomplete.
invalid_amountThe collection quantity is negative.
invalid_agreement_referenceThe collection agreement reference is an invalid identifier.
invalid_tokenThe collection batch token is invalid or malformed.

Batch Modification

Adding Collections

The clientCollectionBatchAdd mutation is used to add collection to a batch that has not been submitted for processing i.e. is in a BatchPending state. Collections are added to a batch in a PaymentCollectionPending state. The nonce must be unique for each collection in a batch.

Multiple Requests

The overall batch size is not restricted. Use multiple clientCollectionBatchAdd calls to construct a single batch for submission. Note that the collections specified in each request are limited to a maximum of 20,000.

Removing Collections

The clientCollectionBatchRemove mutation is used to remove collections from an unprocessed batch. Populate the input collections array field with a set of PaymentCollection IDs. Collections that are removed from a batch are cancelled i.e. in a PaymentCollectionCancelled state and not submitted for processing.

Batch Counts

Use the totalCount field in the response to validate that the batch contains the correct number of items for processing.

Batch Submission

The clientBatchSubmit mutation is used to submit a batch for processing. No modification can be performed on the batch once it has been submitted.

Batch Cancellation

The clientBatchCancel mutation is used to cancel a batch before submission. Collections in a cancelled batch must be re-included in a new batch for processing. The PaymentCollectionBatch and constituent PaymentCollection items transition into a cancelled state.

Note

Batch cancellation is an irrevocable operation. A batch with the status BatchCancelled cannot be processed. A batch that has already been submitted cannot be cancelled.

Batch Statuses

The table below describes the states of a PaymentCollectionBatch.

StatusDescription
BatchPendingThe collection batch has been created and is pending processing.
BatchProcessingThe collection batch has been submitted for processing.
BatchCompletedThe collection batch has been processed and each collection has either completed or failed.
BatchCancelledThe collection batch has been cancelled. No collections were processed.

Payment Collection Statuses

The table below describes the different status values a payment collection can have.

StatusDescription
PaymentCollectionPendingThe collection has been created and is pending processing.
PaymentCollectionCompletedThe collection has been completed and the token has been charged.
PaymentCollectionFailedThe collection has failed with no successful attempts.
PaymentCollectionCancelledThe collection has been cancelled and was not processed.

Transaction Statuses

The table below describes the different status values a transaction (collection attempt) can have.

StatusDescription
TransactionSuccessThe transaction has been successfully processed.
TransactionFailureThe transaction failed to be charged on the user's card. An associated statusReason will be returned with this status.

Failure Reasons

The TransactionFailure status indicates that the card transaction failed to be initiated, and includes a STATUS_REASON explaining the cause.

Potential failure reasons are detailed below:

ReasonDescription
authorizationFailedThe transaction was declined or blocked.
authorizationNotFinalisedThe transaction could not be processed by the acquirer.
blockedByFraudChecksThe transaction was blocked due to fraud checks.
downstreamProviderErrorThe transaction could not be processed due to downstream error.
exceedsCardWithdrawalLimitThe transaction was declined due to withdrawal limits exceeded.
insufficientFundsThe transaction was declined due to insufficient funds.
internalServerErrorThe transaction could not be processed due to a server error.
invalidCardErrorThe transaction was declined due to an expired card.
invalidConfigurationErrorThe client has invalid or missing configuration.
invalidTransactionErrorThe transaction could not be processed due to invalid data.
tokenDecryptionErrorThe payment token could not be decrypted.

Webhooks

Webhooks for batches can be subscribed to by initiating a clientWebhookAdd request to receive collection-batch webhook events.

For more information on receiving webhook events, listing active webhook subscriptions, unsubscribing from webhooks and validating signed webhook subscriptions, please visit the Webhooks page.

Webhook Statuses

The collection-batch webhook will be dispatched for each of the following state updates:

  • BatchPending
  • BatchProcessing
  • BatchCompleted
Example Payload
{
"clientId": "test-client",
"data": {
"externalReference": "TestBatch",
"id": "cGF5bWVudGNvbGxlY3Rpb25iYXRjaC9jZjk5YTYwZC03ZTI2LTQwODgtOTI1ZC04ZTRhNWFkMmY5YjI=",
"nonce": "f86fdce9-2e9c-43e9-9246-7d0a121d6349",
"status": "COMPLETED",
"submittedAt": "2025-01-01T10:00:00.000Z",
"totalCollections": 2,
},
"datetime": "2025-01-01T12:00:00.000Z",
"id": "collection-batch:status:completed:cf99a60d-7e26-4088-925d-8e4a5ad2f9b2",
"type": "collection-batch"
}

Queries

Batch Status

Batch and collection information can be queried via the API. The GetPaymentCollectionBatch example demonstrates fetching the batch status and individual collection states.

Pagination

The collections response field is paginated and returns up to the first 500 results. Use the pageInfo object in the PaymentCollectionConnection response to fetch additional pages. See Pagination for more information.

Collections

Each PaymentCollection has associated attempts that are exposed as PaymentTransaction objects. . The GetPaymentCollection example demonstrates the retrieval of the a collection and related transactions.

Transaction Statuses

The table below describes the different status values a transaction (collection attempt) can have.

StatusDescription
TransactionSuccessThe transaction has been successfully processed.
TransactionFailureThe transaction failed to be charged on the user's card. An associated statusReason will be returned with this status.

Failure Reasons

The TransactionFailure status indicates that the card transaction failed to be initiated, and includes a STATUS_REASON explaining the cause.

Potential failure reasons are detailed below:

ReasonDescription
authorizationFailedThe transaction was declined or blocked.
authorizationNotFinalisedThe transaction could not be processed by the acquirer.
blockedByFraudChecksThe transaction was blocked due to fraud checks.
downstreamProviderErrorThe transaction could not be processed due to downstream error.
exceedsCardWithdrawalLimitThe transaction was declined due to withdrawal limits exceeded.
insufficientFundsThe transaction was declined due to insufficient funds.
internalServerErrorThe transaction could not be processed due to a server error.
invalidCardErrorThe transaction was declined due to an expired card.
invalidConfigurationErrorThe client has invalid or missing configuration.
invalidTransactionErrorThe transaction could not be processed due to invalid data.
tokenDecryptionErrorThe payment token could not be decrypted.