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, whether stored in Vault, or tokenised directly with Stitch. 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. Tokens stored in Vault or obtained from once-off transactions are supported.

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.

Card Tokens

Per collection, the paymentMethods.card.token value may be:

• A card token created through Vault, or
• A card ID tokenised directly with Stitch.

Collection Limits

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

Collection Errors

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

Code	Description
duplicate_nonce	The collection nonce already exists on another collection.
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.

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.

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,
    "successfulCollections": 2,
    "failedCollections": 0
  },
  "datetime": "2025-01-01T12:00:00.000Z",
  "id": "collection-batch:status:completed:cf99a60d-7e26-4088-925d-8e4a5ad2f9b2",
  "type": "collection-batch"
}

Queries

Collection Batch

Any batch and associated collection information can be queried via the API. The GetPaymentCollectionBatch example demonstrates fetching the batch status and individual collection states. Per collection (each node within edges), the initially-specified nonce and externalReference values can be used to associate to the processed payment collection id.

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.

Payment Collection

Each PaymentCollection has associated attempts that are exposed as PaymentTransaction objects. The GetPaymentCollection example demonstrates the retrieval of a collection and the 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.

Test Scenarios

Different failure scenarios can be simulated using specific collection amounts when using a test client. The table below enumerates the mapping between tokens and the resulting transaction status reason.

Amount	Status	Reason
1.01	FAILURE	insufficientFunds
2.02	FAILURE	exceedsCardWithdrawalLimit
3.03	FAILURE	downstreamProviderError
4.04	FAILURE	authorizationFailed
Other	SUCCESS	-

Postman Collection

Batch Collections may be tested using the Postman collection available here. These can be used by specifying your client credentials and supplying the custom request variables where required.