Payment Settlements

Payment settlements provide the payment-level view of settlement activity.

Use Payment Settlements when you need to understand how an individual payment settled, which merchant settlement it belongs to, the settled amount, the settlement status, and when funds became available.

Payment settlement records are useful for reconciliation, accounting, support investigations, and merchant-facing settlement detail.

When to use Payment Settlements

Use Payment Settlements when you need to:

• Review settlement detail for individual payments.

• Connect a payment to a merchant settlement.

• Check settlement status for one or more payments.

• Review settled amount, currency, and availability timing.

• Build reconciliation reports that combine payment and settlement data.

• Investigate payment-level settlement exceptions.

• Support merchant or partner questions about how a specific payment settled.

For payment history and transaction-level search, use Reporting APIs first. For merchant-level settlement batches, use Merchant Settlements. For grouped payment batches, use Batches. For funded movement tied to settlement, use Deposits.

How it works

A payment settlement record connects a completed payment to settlement activity.

A typical payment settlement review flow is:

1. Start with a merchant, payment, merchant settlement, or date range.

2. Retrieve payment settlement records using the relevant endpoint.

3. Review the payment ID, settlement amount, settlement status, and available time.

4. Use the merchant settlement ID to connect the payment to a merchant-level settlement event.

5. Use Batches or Deposits when you need to reconcile settlement activity to grouped payments or funded movement.

Available endpoints

Scope	Path	Description
Merchant payment settlement lines	/MerchantSettlements/merchant-payment-settlements/merchant	Returns merchant payment settlement records for a merchant.
Payment settlements by merchant	/Merchants/{merchantId}/payment-settlements	Returns payment settlement records for a merchant, with optional settlement status filtering.
Payments and settlement lines by date range	/MerchantSettlements/merchant/between	Returns payment data and merchant payment settlement data for a merchant and time window.
Settlement batch payment detail	/MerchantSettlements/settlement-info/{merchantSettlementId}	Returns payment-level detail for a specific merchant settlement.
Payment IDs for a merchant settlement	/MerchantSettlements/payment-ids/merchant-settlement	Returns payment IDs associated with a merchant settlement.

Query parameters

Common query parameters include:

• merchantId

• merchantSettlementId

• status

• startTime

• endTime

• page

• pageSize

• sortByDirection

page defaults to 0 on most settlement endpoints. pageSize defaults to 10 where specified. sortByDirection supports ascending and descending.

Use the merchant ID when reviewing settlement activity for a merchant. Use the merchant settlement ID when drilling into a known settlement. Use date range parameters when building reconciliation reports for a specific settlement window.

Payment settlement objects

Several related objects appear in payment settlement responses.

Merchant payment settlement

A merchant payment settlement describes how a specific payment settled for a merchant.

Field	Type	Description
id	string or null	Unique merchant payment settlement identifier.
paymentId	string	Payment associated with this settlement line.
merchantId	string	Merchant associated with the payment settlement.
merchantLocationId	string	Location associated with the payment settlement.
terminalId	string	Terminal associated with the payment settlement.
amount	object	Settled amount for the payment. Uses amount, amount precision, and currency ID.
merchantSettlementId	string or null	Merchant settlement associated with this payment settlement, when assigned.
settlementStartTime	date-time or null	Start of the settlement window.
settlementEndTime	date-time or null	End of the settlement window.
availableTime	date-time or null	Time funds were or are expected to be available.
settlementType	string	Settlement delivery type. Values include ach and wire.
settlementBeneficiary	object	Beneficiary information for the settlement.
status	string	Current merchant payment settlement status.
transfers	array of strings	Transfer identifiers associated with the settlement line.
created	date-time or null	Date and time the record was created.
updated	date-time or null	Date and time the record was last updated.

Payment settlement

A payment settlement provides a payment-centered settlement view.

Field	Type	Description
id	string or null	Unique payment settlement identifier.
paymentId	string or null	Payment associated with the settlement record.
merchantId	string	Merchant associated with the payment.
merchantLocationId	string	Location associated with the payment.
terminalId	string	Terminal associated with the payment.
settleableAmount	object	Amount available to settle. Uses amount, amount precision, and currency ID.
exchangeLossGain	object	Exchange gain or loss amount, when applicable.
merchantTransactions	array	Conversion or transaction records associated with settlement.
settlementAvailableTime	date-time or null	Time funds were or are expected to be available.
settlementStatus	string	Current payment settlement status.
created	date-time or null	Date and time the record was created.
updated	date-time or null	Date and time the record was last updated.

Payment with merchant payment settlement

Some endpoints return payment data and merchant payment settlement data together.

This response includes:

Field	Type	Description
payment	object	Payment record.
merchantPaymentSettlement	object	Merchant payment settlement record associated with the payment.

Use this response when you want payment details and settlement-line details in the same result set.

Amount fields

Settlement amount fields use an amount object.

Field	Type	Description
amount	number	Numeric amount.
amountPrecision	integer	Number of decimal places used for the amount.
currencyId	integer	Currency identifier for the amount.

Merchant payment settlement status

Merchant payment settlement status indicates the state of a payment-level settlement line.

Supported values include:

• created

• pending

• processing

• completed

• error

Use this status when reviewing merchant payment settlement records and payment-level settlement lines.

Payment settlement status

Payment settlement status indicates the settlement state from the payment perspective.

Supported values include:

• storing

• pending

• settling

• completed

• cancelled

• failed

Use this status when filtering or reviewing payment settlement records from /Merchants/{merchantId}/payment-settlements.

Settlement type

Settlement type identifies the delivery method for the payment settlement.

Supported values include:

• ach

• wire

Settlement beneficiary

Settlement beneficiary identifies who receives the settlement.

The beneficiary object includes:

Field	Type	Description
type	string	Beneficiary type. Values include self and partner.
partnerId	string	Partner associated with the beneficiary.

Choosing the right endpoint

Use /MerchantSettlements/merchant-payment-settlements/merchant when you want merchant payment settlement lines for a merchant and do not need the full payment object in the same response.

Use /Merchants/{merchantId}/payment-settlements when you want payment settlement records for a merchant and want to filter by payment settlement status.

Use /MerchantSettlements/merchant/between when you want payments and merchant payment settlement records together for a merchant and time window.

Use /MerchantSettlements/settlement-info/{merchantSettlementId} when you start from a specific merchant settlement and need the payment-level breakdown.

Use /MerchantSettlements/payment-ids/merchant-settlement when you only need payment IDs for a merchant settlement and will retrieve payment details separately.

Relationship to other Settlement pages

Payment Settlements are part of the broader Settlement model.

Use Payment Settlements when you need payment-level settlement detail. Use Merchant Settlements when you need the merchant-level settlement event. Use Batches when you need to understand grouped payment batches. Use Deposits when you need to confirm funded movement tied to a settlement.

A common pattern is:

1. Use Reporting APIs to find completed payments.

2. Use Payment Settlements to review payment-level settlement detail.

3. Use Merchant Settlements to connect payment-level records to merchant-level settlement events.

4. Use Batches to understand grouped payment activity.

5. Use Deposits to confirm funded movement and deposit status.

Typical integration flows

Review settlement detail for a payment

Goal: explain how a specific payment settled.

High level steps:

1. Start with a payment ID or payment history result.

2. Retrieve payment settlement detail for the merchant.

3. Match the payment ID to the relevant settlement record.

4. Review settlement amount, settlement status, available time, and merchant settlement ID.

Reconcile a merchant settlement to payments

Goal: show the payment-level detail behind a merchant settlement.

High level steps:

1. Start with a merchant settlement ID.

2. Retrieve payment settlement detail for that settlement.

3. Review each payment, settled amount, status, and available time.

4. Match payment-level totals to the merchant settlement and internal ledger.

Build a payment-level settlement report

Goal: build a report that combines payment data and settlement data.

High level steps:

1. Identify the merchant and date range.

2. Retrieve payments and merchant payment settlement records for that time window.

3. Display payment identifiers, payment status, settlement amount, settlement status, and available time.

4. Use merchant settlement IDs to group rows by settlement event.

Investigate settlement exceptions

Goal: identify payment-level settlement items that need review.

High level steps:

1. Retrieve payment settlement records for the merchant.

2. Filter by non-completed settlement statuses.

3. Review payment ID, settlement status, and updated timestamp.

4. Use the merchant settlement ID, batch data, or deposit data for additional context.

Next steps

• Use Merchant Settlements for merchant-level settlement events.

• Use Batches when you need grouped payment batch records.

• Use Deposits when you need funded movement and deposit status.

• Use Reporting APIs when you need payment history before reviewing settlement.

• Use Settlement status codes in the Reference Guide when interpreting settlement states.