Merchant Settlements

Merchant settlements provide the batch level view of settlement activity for a single merchant. Each merchant settlement is a batch that groups one or more payments into a single settlement event, such as a daily or intraday settlement.

Use these APIs when you need to:

List settlement batches for a merchant
Retrieve a specific settlement batch by its identifier
Preview how much is currently settleable for a merchant
In limited cases, trigger settlement for a merchant

Most integrators will use the read operations. The mutating operations are typically used by Bead or under guidance from the Bead team.

Merchant settlement object

Merchant settlement batches are represented by the MerchantSettlement schema.

Key fields

id Unique identifier for this settlement batch
created, updated ISO 8601 timestamps that indicate when the batch was created and last updated
merchantId Identifier of the merchant this settlement belongs to
amount An AmountInfo object representing the settlement amount
- amount numeric value
- amountPrecision number of decimal places
- currencyId currency identifier for the settlement
startTime, endTime Optional ISO 8601 timestamps that describe the window of payments included in this settlement
settlementPaymentType How the settlement will be paid out. Uses SettlementPaymentType and can be ach or wire
statusCode Batch level settlement status, using MerchantSettlementStatus Typical values include created, pending, processing, completed, and error. See Settlement status codes in the Reference Guide for full definitions
merchantPaymentSettlementIds Array of identifiers for MerchantPaymentSettlement records attached to this batch
quoteId, transferId, transferJsonString Optional identifiers and raw transfer information associated with bank or provider transfers

For full field definitions, see the schema reference. The sections below focus on how to query and use merchant settlement batches.

Merchant settlement history

Returns a paginated list of settlement batches for a single merchant.

Endpoint

GET /MerchantSettlements/merchant/{merchantId}

Path parameters

Name

Type

Required

Description

merchantId

string

Yes

Merchant identifier in Bead

Request headers

Header

Value

Authorization

Bearer <access_token>

application/json

Query parameters

Name

Type

Required

Notes

page

integer

Zero based page index. Defaults to 0 if omitted

pageSize

integer

Number of items per page. Defaults to 10 if omitted

sortByDirection

string

Sort order. Uses SortByDirection enum, ascending or descending. Default is ascending

Example request

curl -G "https://api.test.devs.beadpay.io/MerchantSettlements/merchant/mer_4e5a13aa" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "page=0" \
  --data-urlencode "pageSize=20" \
  --data-urlencode "sortByDirection=descending"

Successful response 200

{
  "data": [
    {
      "id": "ms_01J8Z4FH9A",
      "created": "2025-09-01T23:15:05.210Z",
      "updated": "2025-09-01T23:20:10.002Z",
      "merchantId": "mer_4e5a13aa",
      "amount": {
        "amount": 2450.75,
        "amountPrecision": 2,
        "currencyId": 101
      },
      "quoteId": "qt_9c87fe",
      "transferId": "tr_01G9C1Z3M2",
      "transferJsonString": null,
      "startTime": "2025-09-01T00:00:00Z",
      "endTime": "2025-09-01T23:59:59Z",
      "settlementPaymentType": "ach",
      "statusCode": "completed",
      "merchantPaymentSettlementIds": [
        "mps_01J8Z4FDS3",
        "mps_01J8Z4FH2Q"
      ]
    }
  ],
  "total": 1,
  "page": 0,
  "pageSize": 20
}

Field reference

Field

Description

Unique settlement batch identifier

created, updated

ISO 8601 timestamps for creation and last update

merchantId

Merchant identifier

amount

Settlement amount object including value, precision, and currency

startTime, endTime

Optional time window of payments included in this settlement

settlementPaymentType

Payout method for the settlement, for example ach or wire

statusCode

Batch level settlement status. See Settlement status codes page

merchantPaymentSettlementIds

Identifiers of merchant payment settlement lines in this batch

quoteId, transferId

Identifiers used for pricing and funding transfers

transferJsonString

Optional raw transfer payload for auditing or troubleshooting

Error responses

Code

Condition

401

Missing or invalid token

403

Authenticated but not permitted for this merchant

404

Merchant id does not exist or is not visible

Best practices

Use sortByDirection=descending to show the most recent settlements first in UIs
Keep pageSize moderate for interactive use and larger for offline exports
Store the id and statusCode in your own system if you display settlement history in a partner or merchant portal
Use the Payment settlements endpoints to retrieve the payment level breakdown for each batch

Retrieve a merchant settlement by id

Retrieves a single merchant settlement batch by its identifier.

Endpoint

GET /MerchantSettlements/{merchantSettlementId}

Path parameters

Name

Type

Required

Description

merchantSettlementId

string

Yes

Settlement batch identifier

Request headers

Header

Value

Authorization

Bearer <access_token>

application/json

Example request

curl "https://api.test.devs.beadpay.io/MerchantSettlements/ms_01J8Z4FH9A" \
  -H "Authorization: Bearer $TOKEN"

Successful response 200

The response body is a single MerchantSettlement object, with the same fields shown in the previous example.

Error responses

Code

Condition

401

Missing or invalid token

403

Authenticated but not permitted to view this record

404

Settlement id does not exist or is not visible

Usage notes

Use this endpoint for detail views or troubleshooting when you already know the settlement id
For payment level details within the batch, use the endpoints documented on the Payment settlements page

Preview settleable amount for a time window

Returns how much could be settled for a merchant in a specific time window without creating a settlement batch.

Endpoint

GET /MerchantSettlements/settle/window/amount

Query parameters

Name

Type

Required

Notes

merchantId

string

Yes

Merchant identifier

startTime

string

Yes

Inclusive start time in ISO 8601 date time format

endTime

string

Yes

Inclusive end time in ISO 8601 date time format

Example request

curl -G "https://api.test.devs.beadpay.io/MerchantSettlements/settle/window/amount" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "merchantId=mer_4e5a13aa" \
  --data-urlencode "startTime=2025-09-01T00:00:00Z" \
  --data-urlencode "endTime=2025-09-01T23:59:59Z"

Successful response 200

2450.75

The response is a numeric value representing the total amount that could be settled for this merchant in the given window, in the default settlement currency for that merchant.

Preview settleable amount for all eligible payments

Returns how much could be settled for a merchant across all currently eligible payments, without specifying a time window.

Endpoint

GET /MerchantSettlements/settle/amount/merchant

Query parameters

Name

Type

Required

Notes

merchantId

string

Yes

Merchant identifier

Example request

curl -G "https://api.test.devs.beadpay.io/MerchantSettlements/settle/amount/merchant" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "merchantId=mer_4e5a13aa"

Successful response 200

7125.30

Use this endpoint in internal tools when you want a quick answer to “How much is currently available to settle for this merchant” across all eligible payments.

Settle a time window

Creates a merchant settlement batch for a merchant across a specified time window. This endpoint is typically controlled by Bead and should only be used under guidance from the Bead team.

Endpoint

POST /MerchantSettlements/settle/window

Request headers

Header

Value

Authorization

Bearer <access_token>

Content-Type

application/json

Request body

SettleFundsByPaymentWindowRequest

Field

Type

Required

Description

merchantId

string

Yes

Merchant identifier

startTime

string

Yes

Inclusive start of the window, ISO 8601 date time

endTime

string

Yes

Inclusive end of the window, ISO 8601 date time

Example request

curl -X POST "https://api.test.devs.beadpay.io/MerchantSettlements/settle/window" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "mer_4e5a13aa",
    "startTime": "2025-09-01T00:00:00Z",
    "endTime": "2025-09-01T23:59:59Z"
  }'

Successful response

200 OK or 201 Created with a MerchantSettlement object for the new batch

Error responses

Code

Condition

400

Invalid payload or time window

401

Missing or invalid token

403

Not permitted to trigger settlement for this merchant

409

Conflicting settlement in progress or settlement rule violation

Settle all eligible payments for a merchant

Creates a merchant settlement batch that includes all currently eligible payments for a merchant. This is an operational control and should be used carefully.

Endpoint

POST /MerchantSettlements/settle/merchant

Request headers

Header

Value

Authorization

Bearer <access_token>

application/json

Query parameters

Name

Type

Required

Notes

merchantId

string

Yes

Merchant identifier

Example request

curl -X POST "https://api.test.devs.beadpay.io/MerchantSettlements/settle/merchant?merchantId=mer_4e5a13aa" \
  -H "Authorization: Bearer $TOKEN"

Successful response

200 OK or 201 Created with a MerchantSettlement object for the new batch

Error responses

Same as for POST /MerchantSettlements/settle/window.

Usage

Use this endpoint only when you have agreed with Bead on how and when merchants should be settled
Typically used in internal operations tools, not exposed directly to external integrators

The following endpoints also live under MerchantSettlements but are documented on the Payment settlements page:

GET /MerchantSettlements/merchant/between returns payments and merchant payment settlement records for a merchant in a time window
GET /MerchantSettlements/settlement-info/{merchantSettlementId} returns payments and merchant payment settlements for a specific batch
GET /MerchantSettlements/payment-ids/merchant-settlement returns payment identifiers for a specific batch

Use those endpoints when you need the payment level breakdown for a settlement batch.

PreviousSettlement NextPayment Settlements

Last updated 12 days ago

Merchant settlement object

Merchant settlement history

Retrieve a merchant settlement by id

Preview settleable amount for a time window

Preview settleable amount for all eligible payments

Settle a time window

Settle all eligible payments for a merchant

Related endpoints