The Settlement object

Represents a settlement of funds to a merchant's bank account. Settlements aggregate transaction proceeds and transfer them to the merchant's designated bank account.

Fields

Field	Type	Description
id REQUIRED	string	Unique identifier for the settlement
merchantId REQUIRED	string	ID of the merchant receiving the settlement
amount REQUIRED	number	Settlement amount in the smallest currency unit
currency REQUIRED	string	Three-letter ISO currency code
status REQUIRED	SettlementStatus	Current status of the settlement SettlementStatus
bankAccountId OPTIONAL	string	ID of the bank account receiving the settlement
transactionCount REQUIRED	number	Number of transactions included in this settlement
periodStart REQUIRED	string	Start of the settlement period (ISO 8601)
periodEnd REQUIRED	string	End of the settlement period (ISO 8601)
processedAt OPTIONAL	string	ISO 8601 timestamp when the settlement was processed
failureReason OPTIONAL	string	Reason for failure if the settlement failed
createdAt REQUIRED	string	ISO 8601 timestamp when the settlement was created
updatedAt REQUIRED	string	ISO 8601 timestamp when the settlement was last updated

Example

{
  "id": "obj_1a2b3c",
  "merchantId": "merchant_1a2b3c",
  "amount": 5000,
  "currency": "USD",
  "status": "pending",
  "bankAccountId": "bankaccount_1a2b3c",
  "transactionCount": 1,
  "periodStart": "string",
  "periodEnd": "string",
  "createdAt": "2026-01-15T09:30:00Z",
  "updatedAt": "2026-01-15T09:30:00Z"
}