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.
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.
Code | Description |
---|---|
invalid_payment_method | The card payment method information is invalid or incomplete. |
invalid_amount | The collection quantity is negative. |
invalid_agreement_reference | The collection agreement reference is an invalid identifier. |
invalid_token | The 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.
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.
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.
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
.
Status | Description |
---|---|
BatchPending | The collection batch has been created and is pending processing. |
BatchProcessing | The collection batch has been submitted for processing. |
BatchCompleted | The collection batch has been processed and each collection has either completed or failed. |
BatchCancelled | The 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.
Status | Description |
---|---|
PaymentCollectionPending | The collection has been created and is pending processing. |
PaymentCollectionCompleted | The collection has been completed and the token has been charged. |
PaymentCollectionFailed | The collection has failed with no successful attempts. |
PaymentCollectionCancelled | The collection has been cancelled and was not processed. |
Transaction Statuses
The table below describes the different status
values a transaction (collection attempt) can have.
Status | Description |
---|---|
TransactionSuccess | The transaction has been successfully processed. |
TransactionFailure | The 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:
Reason | Description |
---|---|
authorizationFailed | The transaction was declined or blocked. |
authorizationNotFinalised | The transaction could not be processed by the acquirer. |
blockedByFraudChecks | The transaction was blocked due to fraud checks. |
downstreamProviderError | The transaction could not be processed due to downstream error. |
exceedsCardWithdrawalLimit | The transaction was declined due to withdrawal limits exceeded. |
insufficientFunds | The transaction was declined due to insufficient funds. |
internalServerError | The transaction could not be processed due to a server error. |
invalidCardError | The transaction was declined due to an expired card. |
invalidConfigurationError | The client has invalid or missing configuration. |
invalidTransactionError | The transaction could not be processed due to invalid data. |
tokenDecryptionError | The 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.
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.
Status | Description |
---|---|
TransactionSuccess | The transaction has been successfully processed. |
TransactionFailure | The 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:
Reason | Description |
---|---|
authorizationFailed | The transaction was declined or blocked. |
authorizationNotFinalised | The transaction could not be processed by the acquirer. |
blockedByFraudChecks | The transaction was blocked due to fraud checks. |
downstreamProviderError | The transaction could not be processed due to downstream error. |
exceedsCardWithdrawalLimit | The transaction was declined due to withdrawal limits exceeded. |
insufficientFunds | The transaction was declined due to insufficient funds. |
internalServerError | The transaction could not be processed due to a server error. |
invalidCardError | The transaction was declined due to an expired card. |
invalidConfigurationError | The client has invalid or missing configuration. |
invalidTransactionError | The transaction could not be processed due to invalid data. |
tokenDecryptionError | The payment token could not be decrypted. |