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.

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.

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,
  },
  "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.

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 tokens within a collection when using a test client. The table below enumerates the mapping between tokens and the resulting transaction status reason.

Token	Status	Reason
Y2FyZC9iZjVlNGQ4NS0wZjBlLTQ5ZDgtOGZlZS0zZjAzNjEyMDZiODA=	TransactionFailure	authorizationFailed
Y2FyZC84OTQ5ZTIxNS02NTc1LTQzNzMtOTM1ZC1hNzExZTdmNWU3MzU=	TransactionFailure	insufficientFunds
Y2FyZC9mOGU1N2NjMS0xMWIxLTRmZmItOTU4NS0yZjAxZDBmNmRmMWU=	TransactionFailure	downstreamProviderError
Y2FyZC81OTkzM2RjOS01ZjdkLTRiNGMtYjQyOS1lZWI4MWIzMjY1YzA=	TransactionSuccess	-