Settlements

Beta. Settlement reporting requires access to be enabled. Without it, a valid merchant API key receives 403 Forbidden. See Settlement reporting to ask for access.

Settlement and settled-transaction reporting - what a payment processor has settled/deposited to the merchant's bank account. A settlement is one bank deposit, which may span several processor batches.

List Settlements

GET/settlements

Returns a paginated list of settlements (bank deposits) for a given date or date range, based on the settlement (deposit) date. Each settlement summarizes one deposit to the merchant's bank account; retrieve its settled-transaction line items with GET /settlements/{settlementId}.

Either date or fromDate/toDate must be provided.

The endpoint supports filtering and sorting via the filters and sorts parameters (see List Transactions for the filter operator table).

Examples:

Single day: ?date=2026-07-01
Date range, ACH only: ?fromDate=2026-07-01&toDate=2026-07-07&filters=type==Ach
Largest first: ?date=2026-07-01&sorts=-amount

Read type and fundingType together: Card Net and Card Gross are both type: Card, with fundingType: Net or Gross. The amount is the deposited total in either case. See Settlements for how fees and reserves affect each model.

Parameters

Name	In	Type	Description
`date`	query	string (date)	A single day to report on. Either `date` or at least one of `fromDate`/`toDate` must be provided. When `date` is given it takes precedence and the range is that single day. Send a date in YYYY-MM-DD format.
`fromDate`	query	string (date)	Inclusive start of the date range. If omitted while `toDate` is given, the range is the single day `toDate`. Send a date in YYYY-MM-DD format.
`toDate`	query	string (date)	Inclusive end of the date range. If omitted while `fromDate` is given, the range is the single day `fromDate`. Send a date in YYYY-MM-DD format.
`merchantIds`	query	string	Comma-separated list of merchant IDs to report on. Currently, every ID must match the merchant that owns your API key; any other ID is rejected with `401`. Omit it to report on that merchant.
`filters`	query	string	Filter criteria in the format: field==value,field!=value Multiple filters can be separated by commas. Available fields: settlementDate, type, amount, status. netAmount is accepted as a deprecated alias of amount until it is removed.
`sorts`	query	string	Sort criteria as comma-separated field names. Prefix a field with `-` for descending order. Available fields: settlementDate, amount, status. netAmount is accepted as a deprecated alias of amount until it is removed.
`page`	query	integer	Page number to retrieve (starts at 1). For example, if you have 100 records with 10 per page, page 2 gives you records 11 to 20.
`pageSize`	query	integer	Number of records per page. For example, if you have 100 records with 10 per page, page 2 gives you records 11 to 20.

Responses

200

A successful paginated response containing settlements

application/json · SettlementsListResponse

totalCount integer required

Total number of settlements that match the filter criteria

Example: 2

page integer required

The current page number (starts at 1)

Example: 1

pageSize integer required

Number of items per page

Example: 10

totalPages integer required

Total number of pages available

Example: 1

hasNextPage boolean required

True if there are more pages of results available

Example: false

hasPreviousPage boolean required

True if there are previous pages of results available

Example: false

items array of SettlementSummary required

Array of settlements for the current page

Child attributes

id string required

The settlement ID, prefixed with stl_.

Example: "stl_01JZ5F0M3SXA6PDH8YT2M4QWCN"

type string required

The kind of settlement: Card for card payments or Ach for ACH bank transfers.

Read this field together with fundingType. Card Net is type: Card with fundingType: Net; Card Gross is type: Card with fundingType: Gross. These are combinations of existing fields, not additional type values. ACH also supports both funding types.

Allowed: Card, Ach

Example: "Card"

settlementDate string (date) required

The date the settlement was deposited to the merchant's bank account.

Example: "2026-07-01"

currency string required

Allowed: USD, CAD

Example: "USD"

amount integer required

The processor-reported deposit total in minor units. Signed: refunds, fees, and adjustments can produce a negative deposit.

For Card Net, the deposit includes deductions for withheld interchange and discount fees. For Card Gross, those fees are billed separately. Reserve holds and transfers can change the deposited amount in either card funding model. Card transaction lines retain their full settled amounts before these deposit-level deductions.

For ACH, fundingType states whether fees are withheld from the deposit or billed separately.

Example: 121875

fundingType string required

Whether the payment provider withholds its fees from deposits or bills them separately. Read together with type; card and ACH funding terms can differ for the same merchant.

Net: the deposit is after withheld fees. For Card Net, interchange and discount fees apply at the deposit level; the individual card lines remain before those deductions.

Gross: fees are billed separately and do not reduce this deposit. For Card Gross, reserve holds and transfers can still change amount, so it need not equal the sum of card transaction amounts.

Funding type does not determine the fee billing schedule. Use each fee charge's source and chargeDate; monthly billing produces StatementOnly rollups of daily SettlementLinked components. An amount is always returned with a fundingType in scope.

Allowed: Net, Gross

Example: "Net"

netAmount integer required deprecated

Deprecated - read amount instead. This member mirrors amount exactly and cannot hold a different figure. fundingType on this payload states whether that figure is the gross deposit or one already net of withheld fees, and is the only authoritative reading of it. Deprecated on 2026-08-21 and removed one month later in its own release, at which point netAmount also stops being accepted as a filter or sort field.

Its value changed when amount was introduced: for a gross-funded merchant it now reports the gross deposit - the figure that actually reached the bank - so despite its name it is not necessarily a net figure.

Example: 121875

transactionCount integer required

Number of settled-transaction line items in the settlement. Always equal to the length of the lineItems array returned by GET /settlements/{settlementId}, which withholds no line.

Example: 42

status string required

Status of the settlement.

Settled: The settlement has been deposited to the merchant's bank account.

Adjusted: Reserved value; not currently returned.

Allowed: Settled, Adjusted

Example: "Settled"

A net-funded card deposit and a gross-funded ACH deposit, during the netAmount deprecation window

{
  "totalCount": 2,
  "page": 1,
  "pageSize": 10,
  "totalPages": 1,
  "hasNextPage": false,
  "hasPreviousPage": false,
  "items": [
    {
      "id": "stl_01JZ5G4K8WQT2XB7RD9NVMC3EH",
      "type": "Card",
      "settlementDate": "2026-07-14",
      "currency": "USD",
      "amount": 121875,
      "fundingType": "Net",
      "netAmount": 121875,
      "transactionCount": 42,
      "status": "Settled"
    },
    {
      "id": "stl_01JZ5G4K8WYN6PSA3KTE5D2QVX",
      "type": "Ach",
      "settlementDate": "2026-07-14",
      "currency": "USD",
      "amount": 50000,
      "fundingType": "Gross",
      "netAmount": 50000,
      "transactionCount": 1,
      "status": "Settled"
    }
  ]
}

Card Net: one deposit

{
  "totalCount": 1,
  "page": 1,
  "pageSize": 10,
  "totalPages": 1,
  "hasNextPage": false,
  "hasPreviousPage": false,
  "items": [
    {
      "id": "stl_01JZ5F0M3SXA6PDH8YT2M4QWCN",
      "type": "Card",
      "settlementDate": "2026-07-01",
      "currency": "USD",
      "amount": 7275,
      "fundingType": "Net",
      "netAmount": 7275,
      "transactionCount": 2,
      "status": "Settled"
    }
  ]
}

Card Gross: one deposit

{
  "totalCount": 1,
  "page": 1,
  "pageSize": 10,
  "totalPages": 1,
  "hasNextPage": false,
  "hasPreviousPage": false,
  "items": [
    {
      "id": "stl_01JZ5F2R8K6M9WC4Q7X3TDHPBV",
      "type": "Card",
      "settlementDate": "2026-07-01",
      "currency": "USD",
      "amount": 7500,
      "fundingType": "Gross",
      "netAmount": 7500,
      "transactionCount": 2,
      "status": "Settled"
    }
  ]
}

400

Bad request - no date parameters were provided.

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
2010 - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
6900 - SdkCardDeclined - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Allowed: 0, 1000, 1001, 2000, 2010, 2011, 2012, 2013, 2014, 2020, 2021, 2100, 2101, 2102, 2103, 2105, 2201, 2202, 2900, 2901, 2902, 2903, 3000, 3201, 3202, 3203, 3204, 3205, 3299, 3400, 3401, 3501, 3502, 3503, 4000, 4001, 4002, 4003, 4004, 6000, 6001, 6100, 6101, 6102, 6103, 6200, 6201, 6202, 6203, 6300, 6301, 6400, 6500, 6501, 6600, 6700, 6701, 6800, 6801, 6802, 6900, 6901, 6902, 9000, 9999

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

missingDateRange

{
  "code": 2000,
  "status": "Rejected",
  "message": "Either 'date' or 'fromDate'/'toDate' must be provided",
  "traceId": "1-6838be96-74c62f8e2804352739e63476",
  "timestamp": "2026-07-01T20:07:50.4723483Z",
  "errorDetails": []
}

401

Unauthorized response due to an invalid or missing API key.

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
2010 - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
6900 - SdkCardDeclined - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

UnauthorizedError

{
  "code": 1000,
  "status": "Rejected",
  "message": "API key cannot be empty",
  "traceId": "1-6838be96-74c62f8e2804352739e63476",
  "timestamp": "2025-05-29T20:07:50.4723483Z",
  "errorDetails": []
}

403

Requires settlement reporting access to be enabled. A valid API key without this access receives 403 Forbidden. See Reporting access.

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
2010 - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
6900 - SdkCardDeclined - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

reportingAccessDisabled

{
  "code": 1001,
  "status": "Rejected",
  "message": "Settlement reporting API access is not enabled for this merchant.",
  "traceId": "1-6838be96-74c62f8e2804352739e63476",
  "timestamp": "2026-09-16T12:00:00Z",
  "errorDetails": []
}

List Settled Transactions

GET/settlements/transactions

Returns a paginated list of settled transactions for a given date or date range, based on the settlement date. Each item is enriched with the summary of the settlement it belongs to.

Either date or fromDate/toDate must be provided.

The endpoint supports filtering and sorting via the filters and sorts parameters (see List Transactions for the filter operator table).

Examples:

Single day: ?date=2026-07-01
Date range, only unmatched lines: ?fromDate=2026-07-01&toDate=2026-07-07&filters=matchStatus==Unmatched
Largest first: ?date=2026-07-01&sorts=-amount

For Card Net and Card Gross, each line reports its full settled amount before deposit-level fees and reserves. Read settlement.type and fundingType together; fundingType: Net does not mean card fees have been deducted from each line.

Parameters

Name	In	Type	Description
`date`	query	string (date)	A single day to report on. Either `date` or at least one of `fromDate`/`toDate` must be provided. When `date` is given it takes precedence and the range is that single day. Send a date in YYYY-MM-DD format.
`fromDate`	query	string (date)	Inclusive start of the date range. If omitted while `toDate` is given, the range is the single day `toDate`. Send a date in YYYY-MM-DD format.
`toDate`	query	string (date)	Inclusive end of the date range. If omitted while `fromDate` is given, the range is the single day `fromDate`. Send a date in YYYY-MM-DD format.
`merchantIds`	query	string	Comma-separated list of merchant IDs to report on. Currently, every ID must match the merchant that owns your API key; any other ID is rejected with `401`. Omit it to report on that merchant.
`filters`	query	string	Filter criteria in the format: field==value,field!=value Multiple filters can be separated by commas. Available fields: settlementDate, matchStatus, amount. netAmount is accepted as a deprecated alias of amount until it is removed.
`sorts`	query	string	Sort criteria as comma-separated field names. Prefix a field with `-` for descending order. Available fields: settlementDate, matchStatus, amount. netAmount is accepted as a deprecated alias of amount until it is removed.
`page`	query	integer	Page number to retrieve (starts at 1). For example, if you have 100 records with 10 per page, page 2 gives you records 11 to 20.
`pageSize`	query	integer	Number of records per page. For example, if you have 100 records with 10 per page, page 2 gives you records 11 to 20.

Responses

200

A successful paginated response containing settled transactions

application/json · SettledTransactionsListResponse

totalCount integer required

Total number of settled transactions that match the filter criteria

Example: 2

page integer required

The current page number (starts at 1)

Example: 1

pageSize integer required

Number of items per page

Example: 10

totalPages integer required

Total number of pages available

Example: 1

hasNextPage boolean required

True if there are more pages of results available

Example: false

hasPreviousPage boolean required

True if there are previous pages of results available

Example: false

items array of SettlementTransaction required

Array of settled transactions for the current page

Child attributes

settlement SettlementSummary required

A summary of a processor-reported transfer of payment proceeds to the merchant's bank account. It identifies the activity grouped into one deposit and reports its date, currency, total amount, rail, and funding type. See Settlement in the glossary.

Child attributes

id string required

The settlement ID, prefixed with stl_.

Example: "stl_01JZ5F0M3SXA6PDH8YT2M4QWCN"

type string required

The kind of settlement: Card for card payments or Ach for ACH bank transfers.

Allowed: Card, Ach

Example: "Card"

settlementDate string (date) required

The date the settlement was deposited to the merchant's bank account.

Example: "2026-07-01"

currency string required

Allowed: USD, CAD

Example: "USD"

amount integer required

The processor-reported deposit total in minor units. Signed: refunds, fees, and adjustments can produce a negative deposit.

For ACH, fundingType states whether fees are withheld from the deposit or billed separately.

Example: 121875

fundingType string required

Whether the payment provider withholds its fees from deposits or bills them separately. Read together with type; card and ACH funding terms can differ for the same merchant.

Net: the deposit is after withheld fees. For Card Net, interchange and discount fees apply at the deposit level; the individual card lines remain before those deductions.

Gross: fees are billed separately and do not reduce this deposit. For Card Gross, reserve holds and transfers can still change amount, so it need not equal the sum of card transaction amounts.

Allowed: Net, Gross

Example: "Net"

netAmount integer required deprecated

Example: 121875

transactionCount integer required

Number of settled-transaction line items in the settlement. Always equal to the length of the lineItems array returned by GET /settlements/{settlementId}, which withholds no line.

Example: 42

status string required

Status of the settlement.

Settled: The settlement has been deposited to the merchant's bank account.

Adjusted: Reserved value; not currently returned.

Allowed: Settled, Adjusted

Example: "Settled"

transactionId string

The transaction ID, prefixed with trx_. Absent when matchStatus is Unmatched - look it up via GET /transactions (e.g. ?filters=id==trx_...) for full transaction detail.

Example: "trx_01JZ5EXH9GVK3M7T2QSBWD48RC"

transactionType string required

The kind of settled transaction. Treat this list as open: ignore a value your integration does not recognize instead of rejecting the line.

Sale: A sale that deposited funds to the merchant.

Refund: A refund/credit returned to the cardholder or payer (reduces the net deposit).

Capture: The capture/settlement of a previously authorized transaction.

Return: A payout the provider tried to make and could not - for ACH, typically a closed or invalid bank account - so no money reached the merchant. The line exists because the attempt still cost a fee: nothing was disbursed, so for a net-funded rail amount is that fee as a negative, and for a gross-funded one it is zero and the fee is billed separately. Unlike a Refund, no money moved in the first place, so nothing is deducted from the deposit beyond that fee. An ACH entry the bank returns before any money moves is reported the same way, in a settlement for that day, with its fee linked through the line.

Chargeback: Money taken back from the merchant after it was paid out, because the payer's bank returned the payment. Reported for ACH, as a return after funding. amount is negative: the returned amount under gross funding, or the returned amount and the entry's fees under net funding. The line is on the deposit of the day the return settled, and the original sale's line and deposit do not change. transactionDate is the original sale's date. The line matches only a Chargeback transaction: until that transaction exists, matchStatus is Unmatched and transactionId is absent.

See Transaction type for the reporting context.

Allowed: Sale, Refund, Capture, Return, Chargeback

Example: "Sale"

gatewayTransactionId string required

The gateway's own transaction ID.

Example: "1120000006864180230"

batchId string

The processor's own batch number this transaction was settled in (informational). Present for card settlements; absent for providers with no native batch concept (e.g. ACH).

Example: "2616201"

matchStatus string required

Whether the settled transaction has been matched to an API transaction. A Refund line is matched to the refund transaction, never to the sale it refunds; a refund line that resolves only to a sale is left Unmatched. A Return line keeps its link to the sale whose payout failed.

Unmatched: No transaction has been identified for this settled line; transactionId is absent.

Matched: Automatically matched to a transaction.

ManuallyMatched: Matched to a transaction by manual reconciliation.

Allowed: Unmatched, Matched, ManuallyMatched

Example: "Matched"

invoiceNumber string

Populated from the matched transaction, when one exists.

Example: "INV-10432"

paymentType string

Populated from the matched transaction's card type, when one exists.

Example: "Visa"

settlementDate string (date) required

The date the transaction was settled - the parent settlement's deposit date.

Example: "2026-07-01"

transactionDate string (date-time)

The date the underlying transaction was processed, when reported.

Example: "2026-06-30T18:22:41Z"

amount integer required

The settled line amount in minor units. Signed: refunds are negative.

Card Net and Card Gross: the full settled transaction amount before deposit-level fees and reserve adjustments. Card fees are not allocated to individual transaction lines, so fundingType: Net does not make a card line's amount net of those fees.

ACH Net: the disbursed amount less any fees withheld from this line. A zero-disbursement Return can therefore have a negative amount equal to its fee. ACH Gross: the disbursed amount without subtracting separately billed fees; a zero-disbursement line remains zero.

Withheld fees are also itemized by GET /fee-charges. Do not subtract them again from amounts that already include the deduction.

Example: 5000

fundingType string required

The parent settlement's funding type, repeated on this line. Read with settlement.type.

For Card Net and Card Gross, this field describes deposit-level fee withholding; the line's amount remains the full settled transaction amount. For ACH Net, line-level fees are withheld where applicable; for ACH Gross, they are billed separately. Funding type alone does not determine fee billing dates.

Allowed: Net, Gross

Example: "Net"

netAmount integer required deprecated

Deprecated - read amount instead. This member mirrors amount exactly. The enclosing settlement's type and fundingType explain the line amount: card lines retain their full settled amounts under both Card Net and Card Gross; ACH Net lines reflect any fees withheld from that line.

Deprecated on 2026-08-21 and removed one month later in its own release, at which point netAmount also stops being accepted as a filter or sort field. Despite its name, it does not necessarily represent an amount after fees.

Example: 5000

currency string required

Allowed: USD, CAD

Example: "USD"

Card Net: full line amounts, matched and unmatched

{
  "totalCount": 2,
  "page": 1,
  "pageSize": 10,
  "totalPages": 1,
  "hasNextPage": false,
  "hasPreviousPage": false,
  "items": [
    {
      "settlement": {
        "id": "stl_01JZ5F0M3SXA6PDH8YT2M4QWCN",
        "type": "Card",
        "settlementDate": "2026-07-01",
        "currency": "USD",
        "amount": 7275,
        "fundingType": "Net",
        "netAmount": 7275,
        "transactionCount": 2,
        "status": "Settled"
      },
      "transactionId": "trx_01JZ5EXH9GVK3M7T2QSBWD48RC",
      "transactionType": "Sale",
      "gatewayTransactionId": "1120000006864180230",
      "batchId": "2616201",
      "matchStatus": "Matched",
      "invoiceNumber": "INV-10432",
      "paymentType": "Visa",
      "transactionDate": "2026-06-30T18:22:41Z",
      "amount": 5000,
      "netAmount": 5000,
      "currency": "USD",
      "settlementDate": "2026-07-01",
      "fundingType": "Net"
    },
    {
      "settlement": {
        "id": "stl_01JZ5F0M3SXA6PDH8YT2M4QWCN",
        "type": "Card",
        "settlementDate": "2026-07-01",
        "currency": "USD",
        "amount": 7275,
        "fundingType": "Net",
        "netAmount": 7275,
        "transactionCount": 2,
        "status": "Settled"
      },
      "transactionType": "Sale",
      "gatewayTransactionId": "1120000006863240617",
      "batchId": "2616301",
      "matchStatus": "Unmatched",
      "amount": 2500,
      "netAmount": 2500,
      "currency": "USD",
      "settlementDate": "2026-07-01",
      "fundingType": "Net"
    }
  ]
}

Card Gross: full line amounts, fees billed separately

{
  "totalCount": 2,
  "page": 1,
  "pageSize": 10,
  "totalPages": 1,
  "hasNextPage": false,
  "hasPreviousPage": false,
  "items": [
    {
      "settlement": {
        "id": "stl_01JZ5F2R8K6M9WC4Q7X3TDHPBV",
        "type": "Card",
        "settlementDate": "2026-07-01",
        "currency": "USD",
        "amount": 7500,
        "fundingType": "Gross",
        "netAmount": 7500,
        "transactionCount": 2,
        "status": "Settled"
      },
      "transactionId": "trx_01JZ5EXH9GVK3M7T2QSBWD48RC",
      "transactionType": "Sale",
      "gatewayTransactionId": "1120000006864180230",
      "batchId": "2616201",
      "matchStatus": "Matched",
      "invoiceNumber": "INV-10432",
      "paymentType": "Visa",
      "transactionDate": "2026-06-30T18:22:41Z",
      "amount": 5000,
      "netAmount": 5000,
      "currency": "USD",
      "settlementDate": "2026-07-01",
      "fundingType": "Gross"
    },
    {
      "settlement": {
        "id": "stl_01JZ5F2R8K6M9WC4Q7X3TDHPBV",
        "type": "Card",
        "settlementDate": "2026-07-01",
        "currency": "USD",
        "amount": 7500,
        "fundingType": "Gross",
        "netAmount": 7500,
        "transactionCount": 2,
        "status": "Settled"
      },
      "transactionType": "Sale",
      "gatewayTransactionId": "1120000006863240617",
      "batchId": "2616301",
      "matchStatus": "Unmatched",
      "amount": 2500,
      "netAmount": 2500,
      "currency": "USD",
      "settlementDate": "2026-07-01",
      "fundingType": "Gross"
    }
  ]
}

400

Bad request - no date parameters were provided.

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
2010 - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
6900 - SdkCardDeclined - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

missingDateRange

{
  "code": 2000,
  "status": "Rejected",
  "message": "Either 'date' or 'fromDate'/'toDate' must be provided",
  "traceId": "1-6838be96-74c62f8e2804352739e63476",
  "timestamp": "2026-07-01T20:07:50.4723483Z",
  "errorDetails": []
}

401

Unauthorized response due to an invalid or missing API key.

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
2010 - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
6900 - SdkCardDeclined - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

UnauthorizedError

{
  "code": 1000,
  "status": "Rejected",
  "message": "API key cannot be empty",
  "traceId": "1-6838be96-74c62f8e2804352739e63476",
  "timestamp": "2025-05-29T20:07:50.4723483Z",
  "errorDetails": []
}

403

Requires settlement reporting access to be enabled. A valid API key without this access receives 403 Forbidden. See Reporting access.

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
2010 - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
6900 - SdkCardDeclined - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

reportingAccessDisabled

{
  "code": 1001,
  "status": "Rejected",
  "message": "Settlement reporting API access is not enabled for this merchant.",
  "traceId": "1-6838be96-74c62f8e2804352739e63476",
  "timestamp": "2026-09-16T12:00:00Z",
  "errorDetails": []
}

Get Settlement

GET/settlements/{settlementId}

Returns the details of a single settlement (bank deposit), including its settled-transaction line items. A deposit can span several processor batches, so each line item carries its own batchId. For line items with a transactionId, look up the ID via GET /transactions (e.g. ?filters=id==trx_...) for full transaction detail.

Every line item the deposit contains is returned, including any that moved no money, so lineItems always matches the settlement's own transactionCount.

Reconciliation depends on both type and fundingType:

Card Net (type: Card, fundingType: Net): sum of full card line amounts, less withheld interchange and discount fees, plus signed reserve holds and transfers.
Card Gross (type: Card, fundingType: Gross): sum of full card line amounts, plus signed reserve holds and transfers. Fees are billed separately and do not reduce the deposit.
Ach Net (type: Ach, fundingType: Net): sum of line amounts, less any withheld deposit-level fees. The line amounts already reflect fees withheld from individual transactions.
Ach Gross (type: Ach, fundingType: Gross): sum of line amounts, with fees billed separately. Monthly billing produces StatementOnly fee charges dated to the billing month.

The card formulas assume all transaction lines are available. The deposit amount is the processor-reported total; card lines can become available later than that total. Reserve movements are not exposed as transaction lines or billed fee charges, so the line items and fees may not be sufficient to reconstruct the deposit exactly. See the Card Net and Card Gross examples.

Parameters

Name	In	Type	Description
`settlementId` required	path	string	The settlement ID, prefixed with `stl_`.
`merchantIds`	query	string	Comma-separated list of merchant IDs to report on. Currently, every ID must match the merchant that owns your API key; any other ID is rejected with `401`. Omit it to report on that merchant.

Responses

200

The settlement details

application/json · SettlementDetailResponse

id string required

The settlement ID, prefixed with stl_.

Example: "stl_01JZ5F0M3SXA6PDH8YT2M4QWCN"

type string required

The kind of settlement: Card for card payments or Ach for ACH bank transfers.

Allowed: Card, Ach

Example: "Card"

settlementDate string (date) required

The date the settlement was deposited to the merchant's bank account.

Example: "2026-07-01"

currency string required

Allowed: USD, CAD

Example: "USD"

amount integer required

The processor-reported deposit total in minor units. Signed: refunds, fees, and adjustments can produce a negative deposit.

For ACH, fundingType states whether fees are withheld from the deposit or billed separately.

Example: 121875

fundingType string required

Whether the payment provider withholds its fees from deposits or bills them separately. Read together with type; card and ACH funding terms can differ for the same merchant.

Net: the deposit is after withheld fees. For Card Net, interchange and discount fees apply at the deposit level; the individual card lines remain before those deductions.

Gross: fees are billed separately and do not reduce this deposit. For Card Gross, reserve holds and transfers can still change amount, so it need not equal the sum of card transaction amounts.

Allowed: Net, Gross

Example: "Net"

netAmount integer required deprecated

Example: 121875

transactionCount integer required

Number of settled-transaction line items in the settlement. Always equal to the length of the lineItems array returned by GET /settlements/{settlementId}, which withholds no line.

Example: 42

status string required

Status of the settlement.

Settled: The settlement has been deposited to the merchant's bank account.

Adjusted: Reserved value; not currently returned.

Allowed: Settled, Adjusted

Example: "Settled"

merchantId string required

The ID of the merchant the settlement was deposited to, prefixed with mer_.

Example: "mer_01JQZC2Y6W3F8XKT5H9DPNBMVR"

lineItems array of SettlementLineItem required

Child attributes

transactionId string

The transaction ID, prefixed with trx_. Absent when matchStatus is Unmatched - look it up via GET /transactions (e.g. ?filters=id==trx_...) for full transaction detail.

Example: "trx_01JZ5EXH9GVK3M7T2QSBWD48RC"

transactionType string required

The kind of settled transaction. Treat this list as open: ignore a value your integration does not recognize instead of rejecting the line.

Sale: A sale that deposited funds to the merchant.

Refund: A refund/credit returned to the cardholder or payer (reduces the net deposit).

Capture: The capture/settlement of a previously authorized transaction.

See Transaction type for the reporting context.

Allowed: Sale, Refund, Capture, Return, Chargeback

Example: "Sale"

gatewayTransactionId string required

The gateway's own transaction ID.

Example: "1120000006864180230"

batchId string

The processor's own batch number this transaction was settled in (informational). Present for card settlements; absent for providers with no native batch concept (e.g. ACH).

Example: "2616201"

matchStatus string required

Whether the settled transaction has been matched to a transaction. A Refund line is matched to the refund transaction, never to the sale it refunds; a refund line that resolves only to a sale is left Unmatched. A Return line keeps its link to the sale whose payout failed.

Unmatched: No API transaction has been identified for this settled line; transactionId is absent.

Matched: Automatically matched to a transaction.

ManuallyMatched: Matched to a transaction by manual reconciliation.

Allowed: Unmatched, Matched, ManuallyMatched

Example: "Matched"

invoiceNumber string

Populated from the matched transaction, when one exists.

Example: "INV-10432"

paymentType string

Populated from the matched transaction's card type, when one exists.

Example: "Visa"

transactionDate string (date-time)

The date the underlying transaction was processed, when reported.

Example: "2026-06-30T18:22:41Z"

amount integer required

The settled line amount in minor units. Signed: refunds are negative.

Withheld fees are also itemized by GET /fee-charges. Do not subtract them again from amounts that already include the deduction.

Example: 5000

netAmount integer required deprecated

Example: 5000

currency string required

Allowed: USD, CAD

Example: "USD"

Card Net: 7500 in card lines less 225 in withheld fees

{
  "id": "stl_01JZ5F0M3SXA6PDH8YT2M4QWCN",
  "type": "Card",
  "merchantId": "mer_01JQZC2Y6W3F8XKT5H9DPNBMVR",
  "settlementDate": "2026-07-01",
  "currency": "USD",
  "amount": 7275,
  "fundingType": "Net",
  "netAmount": 7275,
  "transactionCount": 2,
  "status": "Settled",
  "lineItems": [
    {
      "transactionId": "trx_01JZ5EXH9GVK3M7T2QSBWD48RC",
      "transactionType": "Sale",
      "gatewayTransactionId": "1120000006864180230",
      "batchId": "2616201",
      "matchStatus": "Matched",
      "invoiceNumber": "INV-10432",
      "paymentType": "Visa",
      "transactionDate": "2026-06-30T18:22:41Z",
      "amount": 5000,
      "netAmount": 5000,
      "currency": "USD"
    },
    {
      "transactionType": "Sale",
      "gatewayTransactionId": "1120000006863240617",
      "batchId": "2616301",
      "matchStatus": "Unmatched",
      "amount": 2500,
      "netAmount": 2500,
      "currency": "USD"
    }
  ]
}

Card Gross: 7500 deposited; fees billed separately

{
  "id": "stl_01JZ5F2R8K6M9WC4Q7X3TDHPBV",
  "type": "Card",
  "merchantId": "mer_01JQZC3X5H9K2MT7R8P4V6NBDW",
  "settlementDate": "2026-07-01",
  "currency": "USD",
  "amount": 7500,
  "fundingType": "Gross",
  "netAmount": 7500,
  "transactionCount": 2,
  "status": "Settled",
  "lineItems": [
    {
      "transactionId": "trx_01JZ5EXH9GVK3M7T2QSBWD48RC",
      "transactionType": "Sale",
      "gatewayTransactionId": "1120000006864180230",
      "batchId": "2616201",
      "matchStatus": "Matched",
      "invoiceNumber": "INV-10432",
      "paymentType": "Visa",
      "transactionDate": "2026-06-30T18:22:41Z",
      "amount": 5000,
      "netAmount": 5000,
      "currency": "USD"
    },
    {
      "transactionType": "Sale",
      "gatewayTransactionId": "1120000006863240617",
      "batchId": "2616301",
      "matchStatus": "Unmatched",
      "amount": 2500,
      "netAmount": 2500,
      "currency": "USD"
    }
  ]
}

Card Gross with a 500 reserve hold: 7000 deposited

{
  "id": "stl_01JZ5F4V9Q8KD2EXM7B5S3R6TH",
  "type": "Card",
  "merchantId": "mer_01JQZC3X5H9K2MT7R8P4V6NBDW",
  "settlementDate": "2026-07-01",
  "currency": "USD",
  "amount": 7000,
  "fundingType": "Gross",
  "netAmount": 7000,
  "transactionCount": 2,
  "status": "Settled",
  "lineItems": [
    {
      "transactionId": "trx_01JZ5EXH9GVK3M7T2QSBWD48RC",
      "transactionType": "Sale",
      "gatewayTransactionId": "1120000006864180230",
      "batchId": "2616201",
      "matchStatus": "Matched",
      "invoiceNumber": "INV-10432",
      "paymentType": "Visa",
      "transactionDate": "2026-06-30T18:22:41Z",
      "amount": 5000,
      "netAmount": 5000,
      "currency": "USD"
    },
    {
      "transactionType": "Sale",
      "gatewayTransactionId": "1120000006863240617",
      "batchId": "2616301",
      "matchStatus": "Unmatched",
      "amount": 2500,
      "netAmount": 2500,
      "currency": "USD"
    }
  ]
}

401

Unauthorized response due to an invalid or missing API key.

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
2010 - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
6900 - SdkCardDeclined - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

UnauthorizedError

{
  "code": 1000,
  "status": "Rejected",
  "message": "API key cannot be empty",
  "traceId": "1-6838be96-74c62f8e2804352739e63476",
  "timestamp": "2025-05-29T20:07:50.4723483Z",
  "errorDetails": []
}

403

Requires settlement reporting access to be enabled. A valid API key without this access receives 403 Forbidden. See Reporting access.

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
2010 - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
6900 - SdkCardDeclined - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

reportingAccessDisabled

{
  "code": 1001,
  "status": "Rejected",
  "message": "Settlement reporting API access is not enabled for this merchant.",
  "traceId": "1-6838be96-74c62f8e2804352739e63476",
  "timestamp": "2026-09-16T12:00:00Z",
  "errorDetails": []
}

404

The settlement does not exist or does not belong to the merchant.

application/json · Error

code integer

Numeric error code. These are grouped into ranges for easier identification and troubleshooting.

0 - Unknown
1000 - AuthenticationGenericError
1001 - MerchantNotAuthorizedForResource
2000 - RequestValidationGenericError
2010 - InvalidPaymentMethodType - The payment method type is not supported for this operation. This includes: ACH tokens cannot be used for auth, void, or subscription transactions.
2011 - InvalidTransactionType
2012 - InvalidAmount
2013 - PaymentMethodUsageRestricted
2014 - PaymentMethodNotEnabled - The payment method or card brand is not enabled for the merchant. Returned with HTTP 400 by POST /transactions/token-sale and POST /transactions/token-auth. The message names what is not enabled: ACH payments are not enabled for this merchant., Card payments are not enabled for this merchant., {Brand} cards are not enabled for this merchant. (Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or Maestro), or This card brand is not enabled for this merchant.
2020 - InvalidPaymentMethodOwner
2021 - InvalidAccountHolderOwner
2100 - InvalidAccountHolderInformation
2101 - InvalidCountryCode
2102 - InvalidZipCode
2103 - MissingCountryCodeOrZipCode
2105 - InvalidEmailAddress
2201 - MissingUniqueToken
2202 - TransactionDeclinedError
2900 - RequestValidationUnsupportedPayload
2901 - RequestValidationWebhookMissingTypeAndDmnType
2902 - RequestValidationUnsupportedWebhookTokenization
2903 - RequestValidationUnsupportedWebhookType
3000 - UnknownServerGenericError
3201 - InvalidOrExpiredSession
3202 - FailedToCreateSessionInAdapter
3203 - ErrorWhileTokenizingCard
3204 - FailedToLoadThirdPartySdk
3205 - SessionExpired
3299 - JavaScriptError
3400 - ResourceNotReadyError
3401 - TransactionNotCompleteYet
3501 - CouldNotCreateBillingSubscription
3502 - CouldNotCancelBillingSubscription
3503 - BillingSubscriptionInvalidStatus
4000 - ResourceNotFound
4001 - TokenizedCardNotFound
4002 - PaymentMethodNotFound
4003 - AccountHolderNotFound
4004 - BillingSubscriptionNotFound
6000 - SdkGenericError
6001 - SdkJavaScriptError
6100 - SdkSessionLoadFailed
6101 - SdkSessionExpired
6102 - SdkSessionNotInitialized
6103 - SdkEnvironmentMismatch
6200 - SdkCardFieldsInvalid
6201 - SdkCardTokenizationFailed
6202 - SdkCardInitFailed
6203 - SdkCardProcessingFailed
6300 - SdkAchFieldsInvalid
6301 - SdkAchProcessingFailed
6400 - SdkEftProcessingFailed
6500 - SdkWalletError
6501 - SdkWalletProcessingFailed
6600 - SdkThirdPartySdkLoadFailed
6700 - SdkFormValidationFailed
6701 - SdkBillingValidationFailed
6800 - Sdk3dsAuthenticationFailed - Issuer ACS rejected the 3DS authentication. Only emitted when formConfig.enable3DSecure: true.
6801 - Sdk3dsAuthenticationUnavailable - 3DS authentication could not be completed due to an upstream technical issue.
6802 - Sdk3dsNotEnrolled - The card is not enrolled in 3DS.
6900 - SdkCardDeclined - The issuer declined the card on the hosted payment form or Payment SDK path. The specific reason is on transactionResponses[0].responseCode (10-18) and in resultText.
6901 - SdkCardGatewayError - The gateway rejected or failed the hosted payment form payment because of validation or a gateway failure rather than an issuer decision.
6902 - SdkCardTokenMissing - The gateway reported no failure but returned no payment token.
9000 - UnhandledGenericError
9999 - MaxErrorCode

Example: 2000

status string

Execution status of the request sent to the payment gateway.

Completed - The request completed successfully.
Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.
Unknown

Allowed: Completed, Rejected, Interrupted, Unknown

Example: "Rejected"

message string

Developer-facing error message.

Example: "One or more validation errors occurred."

traceId string

Unique trace identifier for tracking and debugging this request.

Example: "1-6838bcce-5c0074e82ac7170d4f990d87"

timestamp string (date-time)

The timestamp when the error occurred (UTC).

Example: "2025-05-29T20:00:15.5752808Z"

errorDetails array of ErrorDetail

Child attributes

code integer

Error code

Example: 2000

field string

The field with the error

Example: "Amount"

message string

Error message

Example: "Request validation failed"

details string

Additional details about the error

Example: "The Amount field must be a positive number between 1 and 999,999,999."

settlementNotFound

{
  "code": 4000,
  "status": "Rejected",
  "message": "Settlement stl_01JZ5F0M3SXA6PDH8YT2M4QWCN not found",
  "traceId": "1-6838be96-74c62f8e2804352739e63476",
  "timestamp": "2026-07-01T20:07:50.4723483Z",
  "errorDetails": []
}