Search payments

GET/v1/payments

Search for payments, including charges and payouts, using a variety of criteria. This endpoint supports advanced sorting and filtering options.

ParametersExpand Collapse

PaymentListParams parameters

string customerID

Query param: Search using the customer_id of a charge or payout.

formatuuid

Int defaultPageSize

Query param

formatint32

DefaultSort defaultSort

Query param: The field to sort the results by.

DefaultSortOrder defaultSortOrder

Query param

string externalID

Query param: Search using the external_id of a charge or payout.

string fundingID

Query param: Search using the funding_id of a charge or payout.

formatuuid

Boolean includeMetadata

Query param: Include the metadata for payments in the returned data.

Int maxAmount

Query param: Search using a maximum amount of a charge or payout.

formatint32

DateTimeOffset maxCreatedAt

Query param: Search using the latest created_at date of a charge or payout.

formatdate-time

DateTimeOffset maxEffectiveAt

Query param: Search using the latest effective_date of a charge or payout.

formatdate-time

DateOnly maxPaymentDate

Query param: Search using the latest payment_date of a charge or payout.

formatdate

Int minAmount

Query param: Search using the minimum amount of a chargeorpayout`.

formatint32

DateTimeOffset minCreatedAt

Query param: Search using the earliest created_at date of a charge or payout.

formatdate-time

DateTimeOffset minEffectiveAt

Query param: Search using the earliest effective_date of a charge or payout.

formatdate-time

DateOnly minPaymentDate

Query param: Search using the earliest of a charge or payout.

formatdate

Int pageNumber

Query param: Results page number. Starts at page 1.

formatint32

Int pageSize

Query param: Results page size. Max value: 1000

formatint32

string paykey

Query param: Search using the paykey of a charge or payout.

string paykeyID

Query param: Search using the paykey_id of a charge or payout.

formatuuid

string paymentID

Query param: Search using the id of a charge or payout.

formatuuid

IReadOnlyList<PaymentStatus> paymentStatus

Query param: Search by the status of a charge or payout.

IReadOnlyList<PaymentType> paymentType

Query param: Search by the type of a charge or payout.

string searchText

Query param: Search using a text string associated with a charge or payout.

SortBy sortBy

Query param: The field to sort the results by.

SortOrder sortOrder

Query param

IReadOnlyList<StatusReason> statusReason

Query param: Reason for latest payment status change.

IReadOnlyList<StatusSource> statusSource

Query param: Source of latest payment status change.

string correlationID

Header param: Optional client generated identifier to trace and debug a series of requests.

string requestID

Header param: Optional client generated identifier to trace and debug a request.

string straddleAccountID

Header param: For use by platforms to specify an account id and set scope of a request.

formatuuid

ReturnsExpand Collapse

class PaymentSummaryPagedV1:

required IReadOnlyList<Data> Data

required string ID

Unique identifier for the charge or payout.

formatuuid

required Int Amount

The amount of the charge or payout in cents.

formatint32

required DateTimeOffset CreatedAt

The time the charge or payout was created.

formatdate-time

required string Currency

The currency of the charge or payout. Only USD is supported.

required string? Description

An arbitrary description for the charge or payout.

required string ExternalID

Unique identifier for the charge or payout in your database. This value must be unique across all charges or payouts.

required IReadOnlyList<string> FundingIds

Funding ids.

required string Paykey

Value of the paykey used for the charge or payout.

required DateOnly PaymentDate

The desired date on which the payment should be occur. For charges, this means the date you want the customer to be debited on. For payouts, this means the date you want the funds to be sent from your bank account.

formatdate

required PaymentType PaymentType

The type of payment. Valid values are charge or payout.

One of the following:

required Status Status

The current status of the charge or payout.

One of the following:

required StatusDetailsV1 StatusDetails

Details about the current status of the charge or payout.

required DateTimeOffset ChangedAt

The time the status change occurred.

formatdate-time

required string Message

A human-readable description of the current status.

required Reason Reason

A machine-readable identifier for the specific status, useful for programmatic handling.

One of the following:

required Source Source

Identifies the origin of the status change (e.g., bank_decline, watchtower). This helps in tracking the cause of status updates.

One of the following:

string? Code

The status code if applicable.

required IReadOnlyDictionary<string, string> TraceIds

Trace ids.

required DateTimeOffset UpdatedAt

The time the charge or payout was last updated.

formatdate-time

CustomerDetailsV1 CustomerDetails

Information about the customer associated with the charge or payout.

required string ID

Unique identifier for the customer

formatuuid

required CustomerType CustomerType

The type of customer

One of the following:

required string Email

The customer's email address

required string Name

The name of the customer

required string Phone

The customer's phone number in E.164 format

DateTimeOffset? EffectiveAt

The actual date on which the payment occurred. For charges, this is the date the customer was debited. For payouts, this is the date the funds were sent from your bank account.

formatdate-time

string? FundingID

Unique identifier for the funding event associated with the charge or payout.

formatuuid

IReadOnlyDictionary<string, string>? Metadata

Metadata for payment - only included if requested.

PaykeyDetailsV1 PaykeyDetails

Information about the paykey used for the charge or payout.

required string ID

Unique identifier for the paykey.

formatuuid

required string CustomerID

Unique identifier for the customer associated with the paykey.

formatuuid

required string Label

Human-readable label that combines the bank name and masked account number to help easility represent this paykey in a UI

Int? Balance

The most recent balance of the bank account associated with the paykey in dollars.

formatint32

required Meta Meta

required string ApiRequestID

Unique identifier for this API request, useful for troubleshooting.

formatuuid

required DateTimeOffset ApiRequestTimestamp

Timestamp for this API request, useful for troubleshooting.

formatdate-time

required Int MaxPageSize

Maximum allowed page size for this endpoint.

formatint32

required Int PageNumber

Page number for paginated results.

formatint32

required Int PageSize

Number of items per page in this response.

formatint32

required string SortBy

The field that the results were sorted by.

required SortOrder SortOrder

One of the following:

required Int TotalItems

required Int TotalPages

The number of pages available.

formatint32

required ResponseType ResponseType

Indicates the structure of the returned content.

"object" means the data field contains a single JSON object.
"array" means the data field contains an array of objects.
"error" means the data field contains an error object with details of the issue.
"none" means no data is returned.

One of the following:

Search payments

PaymentListParams parameters = new();

var page = await client.Payments.List(parameters);
await foreach (var item in page.Paginate())
{
    Console.WriteLine(item);
}

{
  "data": [
    {
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "amount": 10000,
      "created_at": "2019-12-27T18:11:19.117Z",
      "currency": "currency",
      "description": "Invoice payment for 100 widgets",
      "external_id": "external_id",
      "funding_ids": [
        "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
      ],
      "paykey": "paykey",
      "payment_date": "2019-12-27",
      "payment_type": "charge",
      "status": "created",
      "status_details": {
        "changed_at": "2019-12-27T18:11:19.117Z",
        "message": "Payment successfully created and awaiting validation.",
        "reason": "insufficient_funds",
        "source": "system",
        "code": null
      },
      "trace_ids": {
        "foo": "string"
      },
      "updated_at": "2019-12-27T18:11:19.117Z",
      "customer_details": {
        "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "customer_type": "individual",
        "email": "ron@swanson.com",
        "name": "Ron Swanson",
        "phone": "+1234567890"
      },
      "effective_at": "2019-12-27T18:11:19.117Z",
      "funding_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "metadata": {
        "foo": "string"
      },
      "paykey_details": {
        "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "customer_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "label": "Bank of America ****1234",
        "balance": 0
      }
    }
  ],
  "meta": {
    "api_request_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "api_request_timestamp": "2019-12-27T18:11:19.117Z",
    "max_page_size": 0,
    "page_number": 0,
    "page_size": 0,
    "sort_by": "sort_by",
    "sort_order": "asc",
    "total_items": 0,
    "total_pages": 0
  },
  "response_type": "object"
}

Returns Examples

{
  "data": [
    {
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "amount": 10000,
      "created_at": "2019-12-27T18:11:19.117Z",
      "currency": "currency",
      "description": "Invoice payment for 100 widgets",
      "external_id": "external_id",
      "funding_ids": [
        "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
      ],
      "paykey": "paykey",
      "payment_date": "2019-12-27",
      "payment_type": "charge",
      "status": "created",
      "status_details": {
        "changed_at": "2019-12-27T18:11:19.117Z",
        "message": "Payment successfully created and awaiting validation.",
        "reason": "insufficient_funds",
        "source": "system",
        "code": null
      },
      "trace_ids": {
        "foo": "string"
      },
      "updated_at": "2019-12-27T18:11:19.117Z",
      "customer_details": {
        "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "customer_type": "individual",
        "email": "ron@swanson.com",
        "name": "Ron Swanson",
        "phone": "+1234567890"
      },
      "effective_at": "2019-12-27T18:11:19.117Z",
      "funding_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "metadata": {
        "foo": "string"
      },
      "paykey_details": {
        "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "customer_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "label": "Bank of America ****1234",
        "balance": 0
      }
    }
  ],
  "meta": {
    "api_request_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "api_request_timestamp": "2019-12-27T18:11:19.117Z",
    "max_page_size": 0,
    "page_number": 0,
    "page_size": 0,
    "sort_by": "sort_by",
    "sort_order": "asc",
    "total_items": 0,
    "total_pages": 0
  },
  "response_type": "object"
}