Payment Settlements

Payment settlements provide the payment level view of settlement activity. These records describe how individual payments were settled, which merchant settlement batches they belong to, and when funds became available.

Use these APIs when you need to:

  • See settlement information for individual payments

  • Correlate payments with merchant settlement batches

  • Filter payment settlements by merchant and status

  • Build detailed reconciliation reports that combine payment and settlement data

Most integrators call these endpoints from internal reporting jobs or support tools rather than from end user applications.

Authentication and headers

All endpoints on this page are authenticated and use the same headers as other API endpoints.

Required headers

Header
Value

Authorization

Bearer <access_token>

Accept

application/json

Where a request body is present, also include:

Header
Value

Content-Type

application/json

Payment settlement objects

Several related schemas appear in the API for payment level settlement.

MerchantPaymentSettlement

MerchantPaymentSettlement describes how a specific payment was settled for a merchant.

Key fields include:

  • id Unique identifier for the merchant payment settlement record

  • paymentId Identifier of the payment this settlement line refers to

  • merchantId, merchantLocationId, terminalId Identifiers that tie the settlement line back to the merchant, location, and terminal

  • amount An AmountInfo object representing the settled amount for this payment, including value, precision, and currency

  • merchantSettlementId Identifier of the merchant settlement batch that this payment is part of, if any

  • settlementStartTime and settlementEndTime Window used to include this payment in a settlement

  • availableTime When funds from this payment are expected to be available

  • settlementType How the settlement is delivered, for example ach or wire

  • settlementBeneficiary A SettlementBeneficiary object that describes who is receiving funds and which account is used

  • status A MerchantPaymentSettlementStatus value. Typical values are created, pending, processing, completed, and error. See the Settlement status codes page for definitions

  • transfers List of identifiers for transfers associated with this settlement line

Use MerchantPaymentSettlement when you care about payment level settlement lines and their link to merchant settlement batches.

PaymentSettlement

PaymentSettlement provides a more aggregated view focused on the settlement lifecycle of a payment.

Key fields include:

  • settleableAmount Amount that could be settled for the payment

  • exchangeLossGain and related fields Amounts that reflect currency conversion effects when converting between currencies

  • settlementAvailableTime When settlement funds are expected to be available

  • settlementStatus A SettlementStatus value such as storing, pending, settling, completed, cancelled, or failed. See the Settlement status codes page for definitions

Use PaymentSettlement when you want to see settlement status and monetary breakdowns from the payment perspective without linking directly to merchant settlement batch identifiers.

PaymentMerchantPaymentSettlement

PaymentMerchantPaymentSettlement combines:

  • A payment object

  • A merchantPaymentSettlement object

This is returned by endpoints that join payment data and merchant payment settlement data in a single result. It is useful for reconciliation and detailed reporting.

For full field definitions, refer to the schema reference. This page focuses on how to query and use these objects.

List merchant payment settlements for a merchant

Use this endpoint to list MerchantPaymentSettlement records for a merchant. Each record represents settlement information for one payment.

Endpoint

GET /MerchantSettlements/merchant-payment-settlements/merchant

Query parameters

Name
Type
Required
Notes

merchantId

string

Yes

Identifier of the merchant

page

integer

No

Zero based page index, default is 0

pageSize

integer

No

Number of items per page, default is 10

Example request

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

Successful response 200

{
  "data": [
    {
      "id": "mps_01J8Z4FDS3",
      "paymentId": "pay_01J8Z1R9K6",
      "merchantId": "mer_4e5a13aa",
      "merchantLocationId": "loc_bfdc6a7f",
      "terminalId": "term_12345678",
      "amount": {
        "amount": 24.6,
        "amountPrecision": 2,
        "currencyId": 101
      },
      "merchantSettlementId": "ms_01J8Z4FH9A",
      "settlementStartTime": "2025-09-01T00:00:00Z",
      "settlementEndTime": "2025-09-01T23:59:59Z",
      "availableTime": "2025-09-02T09:00:00Z",
      "settlementType": "ach",
      "settlementBeneficiary": {
        "beneficiaryType": "merchant",
        "displayName": "Downtown Flagship",
        "maskedAccount": "****1234"
      },
      "status": "completed",
      "transfers": [
        "tr_01G9C1Z3M2"
      ],
      "created": "2025-09-01T23:15:05.210Z",
      "updated": "2025-09-01T23:20:10.002Z"
    }
  ],
  "page": 0,
  "pageSize": 20,
  "total": 1
}

Usage

  • Use this endpoint when you want a pure settlement line view scoped to a single merchant

  • Use merchantSettlementId to link each line to a batch on the Merchant settlements page

List payment settlements for a merchant with status

Use this endpoint when you want to see PaymentSettlement records filtered by settlement status.

Endpoint

GET /Merchants/{merchantId}/payment-settlements

Path parameters

Name
Type
Required
Description

merchantId

string

Yes

Merchant identifier

Query parameters

Name
Type
Required
Notes

status

string

No

Settlement status filter. Uses SettlementStatus

page

integer

No

Zero based page index

pageSize

integer

No

Number of items per page

Example request

curl -G "https://api.test.devs.beadpay.io/Merchants/mer_4e5a13aa/payment-settlements" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "status=completed" \
  --data-urlencode "page=0" \
  --data-urlencode "pageSize=50"

Successful response 200

{
  "data": [
    {
      "paymentId": "pay_01J8Z1R9K6",
      "settleableAmount": {
        "amount": 24.6,
        "amountPrecision": 2,
        "currencyId": 101
      },
      "exchangeLossGain": {
        "amount": -0.4,
        "amountPrecision": 2,
        "currencyId": 101
      },
      "settlementAvailableTime": "2025-09-02T09:00:00Z",
      "settlementStatus": "completed"
    }
  ],
  "page": 0,
  "pageSize": 50,
  "total": 1
}

Usage

  • Use when you want a payment centric view of settlement state for a merchant

  • Filter by status to build exception dashboards (for example non completed statuses)

  • Combine with payment history endpoints if you need the full payment object

Payments and settlement lines between dates

Use this endpoint to retrieve payments and their merchant payment settlement records for a merchant in a given time window.

Endpoint

GET /MerchantSettlements/merchant/between

Query parameters

Name
Type
Required
Notes

merchantId

string

Yes

Merchant identifier

startTime

string

Yes

Inclusive start time, ISO 8601 date time

endTime

string

Yes

Inclusive end time, ISO 8601 date time

page

integer

No

Zero based page index

pageSize

integer

No

Number of items per page

sortByDirection

string

No

ascending or descending using SortByDirection

Example request

curl -G "https://api.test.devs.beadpay.io/MerchantSettlements/merchant/between" \
  -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" \
  --data-urlencode "page=0" \
  --data-urlencode "pageSize=100" \
  --data-urlencode "sortByDirection=descending"

Successful response 200

{
  "data": [
    {
      "payment": {
        "id": "pay_01J8Z1R9K6",
        "created": "2025-09-01T14:22:11.015Z",
        "statusCode": "completed",
        "amounts": {
          "requested": {
            "inRequestedCurrency": {
              "amount": 25.0,
              "amountPrecision": 2,
              "currencyId": 101
            }
          }
        },
        "reference": "INV-10452"
      },
      "merchantPaymentSettlement": {
        "id": "mps_01J8Z4FDS3",
        "merchantSettlementId": "ms_01J8Z4FH9A",
        "amount": {
          "amount": 24.6,
          "amountPrecision": 2,
          "currencyId": 101
        },
        "status": "completed",
        "settlementStartTime": "2025-09-01T00:00:00Z",
        "settlementEndTime": "2025-09-01T23:59:59Z",
        "availableTime": "2025-09-02T09:00:00Z"
      }
    }
  ],
  "page": 0,
  "pageSize": 100,
  "total": 1
}

Usage

  • Use when you want payments and settlement lines together in one call for a specific time window

  • Ideal for reconciliation reports that need both payment level and settlement level information

Payment settlements for a specific merchant settlement batch

When you already have a merchant settlement batch identifier, you can retrieve the payment level details using these endpoints.

Payments and merchant payment settlements for a batch

Endpoint

GET /MerchantSettlements/settlement-info/{merchantSettlementId}

Path parameters

Name
Type
Required
Description

merchantSettlementId

string

Yes

Settlement batch identifier

Example request

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

Successful response 200

{
  "data": [
    {
      "payment": {
        "id": "pay_01J8Z1R9K6",
        "created": "2025-09-01T14:22:11.015Z",
        "statusCode": "completed"
      },
      "merchantPaymentSettlement": {
        "id": "mps_01J8Z4FDS3",
        "amount": {
          "amount": 24.6,
          "amountPrecision": 2,
          "currencyId": 101
        },
        "status": "completed",
        "availableTime": "2025-09-02T09:00:00Z"
      }
    }
  ],
  "page": 0,
  "pageSize": 50,
  "total": 1
}

Usage

  • Use when you start from a settlement batch and need the full payment level breakdown

  • Often used to power a “view settlement details” screen in a portal or internal tool

Payment identifiers for a batch

Endpoint

GET /MerchantSettlements/payment-ids/merchant-settlement

Query parameters

Name
Type
Required
Notes

merchantSettlementId

string

Yes

Settlement batch identifier

page

integer

No

Zero based page index

pageSize

integer

No

Number of items per page

Example request

curl -G "https://api.test.devs.beadpay.io/MerchantSettlements/payment-ids/merchant-settlement" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "merchantSettlementId=ms_01J8Z4FH9A" \
  --data-urlencode "page=0" \
  --data-urlencode "pageSize=100"

Successful response 200

[
  "pay_01J8Z1R9K6",
  "pay_01J8Z1S3B9"
]

Usage

  • Use when you only need payment identifiers for a batch and will look up payments separately via Reporting

  • Helps keep the payload small if your existing systems are already wired around payment ids

Error responses

Common error responses across these endpoints:

Code
Condition

401

Missing or invalid access token

403

Authenticated but not permitted to view settlements for this merchant or batch

404

Merchant or settlement id does not exist or is not visible

Log the response body and headers for debugging, but avoid exposing raw error details directly to end users.

Choosing the right payment settlement endpoint

A simple way to choose between these endpoints:

  • Use GET /MerchantSettlements/merchant-payment-settlements/merchant when you want all MerchantPaymentSettlement lines for a merchant and do not need the full payment object in the same response

  • Use GET /Merchants/{merchantId}/payment-settlements when you want PaymentSettlement records filtered by settlement status for a merchant

  • Use GET /MerchantSettlements/merchant/between when you want payments and MerchantPaymentSettlement lines together for a merchant and time window

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

  • Use GET /MerchantSettlements/payment-ids/merchant-settlement when you only need payment identifiers for a batch and will look up payments separately

For status values that appear on these objects, see the Settlement status codes page in the Reference Guide.

PreviousMerchant SettlementsNextReporting

Last updated