Source: https://billingmart.com/developers/api/payments

# Payments

What was paid, how, and what is still owed. Recording and refunding are API-key scopes or approved actions, never a connected assistant on its own.

[All sections](https://billingmart.com/developers/api) [Authentication](https://billingmart.com/developers/authentication)

**On this page**

- GET List
- GET Get
- GET List
- GET Get
- GET Summary
- GET Views
- POST Disable
- GET Receipt pdf
- GET Notes
- POST Notes
- POST Record
- POST Refund
- GET List
- GET List
- GET List
- GET List
- GET Get
- OBJ Payment
- OBJ PaymentLink
- OBJ PaymentLinkSummary
- OBJ PaymentLinkViews
- OBJ PaymentNote
- OBJ SavedPaymentMethod
- OBJ MerchantApplicationSummary
- OBJ RateRequestSummary
- OBJ MerchantAccountView

On this page

- GET List
- GET Get
- GET List
- GET Get
- GET Summary
- GET Views
- POST Disable
- GET Receipt pdf
- GET Notes
- POST Notes
- POST Record
- POST Refund
- GET List
- GET List
- GET List
- GET List
- GET Get
- OBJ Payment
- OBJ PaymentLink
- OBJ PaymentLinkSummary
- OBJ PaymentLinkViews
- OBJ PaymentNote
- OBJ SavedPaymentMethod
- OBJ MerchantApplicationSummary
- OBJ RateRequestSummary
- OBJ MerchantAccountView

payments

## List

GET `/v1/payments`

List payments, newest first.

Scope `payments:read`

Effect Read only

MCP tool `list_payments`

Retries Safe to repeat

### Parameters

List parameters
| Name | In | Type | Notes |
| --- | --- | --- | --- |
| `limit`optional | query | `integer` | min 1 · max 50 |
| `cursor`optional | query | `string` | up to 256 chars |
| `invoiceId`optional | query | `id` | — |
| `status`optional | query | `enum` | One of `pending`, `processing`, `authorized`, `succeeded`, `declined`, `failed`, `voided`, `refunded`, `returned` |
| `includeAuthorization`optional | query | `boolean` | — |

### Returns

`data`: [`Payment[]`](https://billingmart.com/developers/api/payments#object-Payment) . Pass `meta.cursor` back as `cursor` for the next page.

Example request Sample

```
curl -X GET "https://api.billingmart.com/v1/payments" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"
```

payments

## Get

GET `/v1/payments/{paymentId}`

One payment.

Scope `payments:read`

Effect Read only

MCP tool `get_payment`

Retries Safe to repeat

### Parameters

Get parameters
| Name | In | Type | Notes |
| --- | --- | --- | --- |
| `paymentId`required | path | `id` | — |
| `includeAuthorization`optional | query | `boolean` | — |

### Returns

`data`: [`Payment`](https://billingmart.com/developers/api/payments#object-Payment)

Example request Sample

```
curl -X GET "https://api.billingmart.com/v1/payments/{paymentId}" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"
```

payment links

## List

GET `/v1/payment-links`

List payment links, newest first: pricing, capacity, counts and status.

Scope `payments:read`

Effect Read only

MCP tool `list_payment_links`

Retries Safe to repeat

### Parameters

List parameters
| Name | In | Type | Notes |
| --- | --- | --- | --- |
| `limit`optional | query | `integer` | min 1 · max 50 |
| `cursor`optional | query | `string` | up to 256 chars |
| `status`optional | query | `enum` | One of `active`, `disabled`, `soldOut`, `completed` |

### Returns

`data`: [`PaymentLink[]`](https://billingmart.com/developers/api/payments#object-PaymentLink) . Pass `meta.cursor` back as `cursor` for the next page.

Example request Sample

```
curl -X GET "https://api.billingmart.com/v1/payment-links" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"
```

payment links

## Get

GET `/v1/payment-links/{linkId}`

One payment link.

Scope `payments:read`

Effect Read only

MCP tool `get_payment_link`

Retries Safe to repeat

### Parameters

Get parameters
| Name | In | Type | Notes |
| --- | --- | --- | --- |
| `linkId`required | path | `id` | — |

### Returns

`data`: [`PaymentLink`](https://billingmart.com/developers/api/payments#object-PaymentLink)

Example request Sample

```
curl -X GET "https://api.billingmart.com/v1/payment-links/{linkId}" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"
```

payment links

## Summary

GET `/v1/payment-links/{linkId}/summary`

A payment link's settings and what it has done: views (all time, the last week and the last month), checkouts started, paid and abandoned by reason, money collected (gross and net of refunds), conversion, last activity and a daily series for the last month. A link of another business is NOT_FOUND.

Scope `payments:read`

Effect Read only

MCP tool `get_payment_link_summary`

Retries Safe to repeat

### Parameters

Summary parameters
| Name | In | Type | Notes |
| --- | --- | --- | --- |
| `linkId`required | path | `id` | — |

### Returns

`data`: [`PaymentLinkSummary`](https://billingmart.com/developers/api/payments#object-PaymentLinkSummary)

Errors this route can answer besides the shared ones: `NOT_FOUND` .

Example request Sample

```
curl -X GET "https://api.billingmart.com/v1/payment-links/{linkId}/summary" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"
```

payment links

## Views

GET `/v1/payment-links/{linkId}/views`

Who opened a payment link: when, country, region and browser family, newest first, a page at a time by cursor. No address and no user agent is ever returned.

Scope `payments:read`

Effect Read only

MCP tool `list_payment_link_views`

Retries Safe to repeat

### Parameters

Views parameters
| Name | In | Type | Notes |
| --- | --- | --- | --- |
| `linkId`required | path | `id` | — |
| `cursor`optional | query | `string` | up to 512 chars |

### Returns

`data`: [`PaymentLinkViews`](https://billingmart.com/developers/api/payments#object-PaymentLinkViews)

Errors this route can answer besides the shared ones: `NOT_FOUND` .

Example request Sample

```
curl -X GET "https://api.billingmart.com/v1/payment-links/{linkId}/views" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"
```

payment links

## Disable

POST `/v1/payment-links/{linkId}/disable`

Turn a payment link off: it takes no payment until it is turned back on, which is an action a person approves.

Scope `actions:propose`

Effect Writes a draft or record

MCP tool `disable_payment_link`

Retries Send an Idempotency-Key; a repeat replays the stored answer for 24 hours

### Parameters

Disable parameters
| Name | In | Type | Notes |
| --- | --- | --- | --- |
| `linkId`required | path | `id` | — |

### Returns

`data`: `object`

Errors this route can answer besides the shared ones: `NOT_FOUND` , `PERMISSION_DENIED` .

Example request Sample

```
curl -X POST "https://api.billingmart.com/v1/payment-links/{linkId}/disable" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

payments

## Receipt pdf

GET `/v1/payments/{paymentId}/receipt-pdf`

Render (or reuse) the receipt PDF for a succeeded payment and return a short-lived signed URL.

Scope `payments:read`

Effect Read only

MCP tool `get_receipt_pdf`

Retries Safe to repeat

### Parameters

Receipt pdf parameters
| Name | In | Type | Notes |
| --- | --- | --- | --- |
| `paymentId`required | path | `id` | — |

### Returns

`data`: [`PdfPreview`](https://billingmart.com/developers/api/invoices#object-PdfPreview)

Example request Sample

```
curl -X GET "https://api.billingmart.com/v1/payments/{paymentId}/receipt-pdf" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"
```

payments

## Notes

GET `/v1/payments/{paymentId}/notes`

The internal notes on one payment, newest first.

Scope `payments:read`

Effect Read only

MCP tool `list_payment_notes`

Retries Safe to repeat

### Parameters

Notes parameters
| Name | In | Type | Notes |
| --- | --- | --- | --- |
| `paymentId`required | path | `id` | — |
| `limit`optional | query | `integer` | min 1 · max 50 |
| `cursor`optional | query | `string` | up to 256 chars |

### Returns

`data`: [`PaymentNote[]`](https://billingmart.com/developers/api/payments#object-PaymentNote) . Pass `meta.cursor` back as `cursor` for the next page.

Example request Sample

```
curl -X GET "https://api.billingmart.com/v1/payments/{paymentId}/notes" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"
```

payments

## Notes

POST `/v1/payments/{paymentId}/notes`

Add an internal note to a payment (plain text, at most 2,000 characters). Append-only: a note is never edited or deleted, never shown to the customer, and never moves money.

Scope `payments:notes`

Effect Writes a draft or record

MCP tool `add_payment_note`

Retries Send an Idempotency-Key; a repeat replays the stored answer for 24 hours

### Parameters

Notes parameters
| Name | In | Type | Notes |
| --- | --- | --- | --- |
| `paymentId`required | path | `id` | — |

### Request body

JSON. Money is an integer count of minor units beside its currency; quantities are thousandths.

Notes request body
| Field | Type | Notes |
| --- | --- | --- |
| `text`required | `string` | up to 2000 chars |

### Returns

`data`: `object`

Example request Sample

```
curl -X POST "https://api.billingmart.com/v1/payments/{paymentId}/notes" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"text":"<text>"}'
```

payments

## Record

POST `/v1/invoices/{invoiceId}/payments`

Record a payment taken OUTSIDE the gateway (cash, check, bank transfer) against an open invoice. Idempotent on method + reference + amount.

Scope `payments:record`

Effect Writes a draft or record

MCP tool None — REST and API keys only

Retries Send an Idempotency-Key; a repeat replays the stored answer for 24 hours

### Parameters

Record parameters
| Name | In | Type | Notes |
| --- | --- | --- | --- |
| `invoiceId`required | path | `id` | — |

### Request body

JSON. Money is an integer count of minor units beside its currency; quantities are thousandths.

Record request body
| Field | Type | Notes |
| --- | --- | --- |
| `method`required | `enum` | One of `cash`, `check`, `bankTransfer`, `other` |
| `reference`required | `string` | up to 128 chars |
| `amount`required | `object` | — |
| `amount.minorUnits`required | `integer` | — |
| `amount.currency`required | `Currency` | — |
| `receivedOn`optional | `string` | matches `^\d{4}-\d{2}-\d{2}$` |
| `sendReceipt`optional | `boolean` | — |

### Returns

`data`: `object`

Example request Sample

```
curl -X POST "https://api.billingmart.com/v1/invoices/{invoiceId}/payments" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"method":"cash","reference":"<reference>","amount":{"minorUnits":0,"currency":"USD"}}'
```

payments

## Refund

POST `/v1/payments/{paymentId}/refund`

Refund a succeeded payment, in full or in part. `idempotencyKey` is required: a retried refund must never become two.

Scope `payments:refund`

Effect Writes a draft or record

MCP tool None — REST and API keys only

Retries Send an Idempotency-Key; a repeat replays the stored answer for 24 hours

### Parameters

Refund parameters
| Name | In | Type | Notes |
| --- | --- | --- | --- |
| `paymentId`required | path | `id` | — |

### Request body

JSON. Money is an integer count of minor units beside its currency; quantities are thousandths.

Refund request body
| Field | Type | Notes |
| --- | --- | --- |
| `amount`optional | `object` | — |
| `amount.minorUnits`required | `integer` | — |
| `amount.currency`required | `Currency` | — |
| `reason`required | `string` | up to 500 chars |
| `idempotencyKey`required | `string` | at least 8 chars · up to 128 chars |

### Returns

`data`: `object`

Example request Sample

```
curl -X POST "https://api.billingmart.com/v1/payments/{paymentId}/refund" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"amount":{"minorUnits":0,"currency":"USD"},"reason":"<reason>","idempotencyKey":"<idempotencyKey>"}'
```

payment methods

## List

GET `/v1/clients/{clientId}/payment-methods`

A client’s saved payment methods as HANDLES: id, card or bank, last four, card type, expiry, label, whether it is usable. Never a vault id.

Scope `payments:read`

Effect Read only

MCP tool `list_payment_methods`

Retries Safe to repeat

### Parameters

List parameters
| Name | In | Type | Notes |
| --- | --- | --- | --- |
| `clientId`required | path | `id` | — |

### Returns

`data`: [`SavedPaymentMethod[]`](https://billingmart.com/developers/api/payments#object-SavedPaymentMethod) . Pass `meta.cursor` back as `cursor` for the next page.

Example request Sample

```
curl -X GET "https://api.billingmart.com/v1/clients/{clientId}/payment-methods" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"
```

merchant applications

## List

GET `/v1/admin/merchant-applications`

List the workspace’s merchant account applications: status, business name, dates, and the Producer ID once approved. Nothing the application carried.

Scope `admin:read`

Effect Read only

MCP tool `list_merchant_applications`

Retries Safe to repeat

### Parameters

List parameters
| Name | In | Type | Notes |
| --- | --- | --- | --- |
| `limit`optional | query | `integer` | min 1 · max 50 |
| `cursor`optional | query | `string` | up to 256 chars |

### Returns

`data`: [`MerchantApplicationSummary[]`](https://billingmart.com/developers/api/payments#object-MerchantApplicationSummary) . Pass `meta.cursor` back as `cursor` for the next page.

Example request Sample

```
curl -X GET "https://api.billingmart.com/v1/admin/merchant-applications" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"
```

rate requests

## List

GET `/v1/admin/rate-requests`

List the workspace’s merchant rate requests: status, business name, dates, and the proposed rates once quoted.

Scope `admin:read`

Effect Read only

MCP tool `list_rate_requests`

Retries Safe to repeat

### Parameters

List parameters
| Name | In | Type | Notes |
| --- | --- | --- | --- |
| `limit`optional | query | `integer` | min 1 · max 50 |
| `cursor`optional | query | `string` | up to 256 chars |

### Returns

`data`: [`RateRequestSummary[]`](https://billingmart.com/developers/api/payments#object-RateRequestSummary) . Pass `meta.cursor` back as `cursor` for the next page.

Example request Sample

```
curl -X GET "https://api.billingmart.com/v1/admin/rate-requests" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"
```

merchant accounts

## List

GET `/v1/admin/merchant-accounts`

The workspace’s merchant accounts: each one’s id and label, whether it is the default or archived, whether test and live are set up, whether its self-tests passed, whether live is activated, and whether it charges live or test right now. Use an id as `merchantAccountId` on a draft invoice. Yes-or-no answers and the label only; never a credential, a producer id, a host or a timestamp. Credentials are entered only by a person in the console.

Scope `admin:read`

Effect Read only

MCP tool `list_merchant_accounts`

Retries Safe to repeat

### Returns

`data`: [`MerchantAccountView[]`](https://billingmart.com/developers/api/payments#object-MerchantAccountView) . Pass `meta.cursor` back as `cursor` for the next page.

Example request Sample

```
curl -X GET "https://api.billingmart.com/v1/admin/merchant-accounts" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"
```

gateway status

## Get

GET `/v1/admin/gateway-status`

Whether the payment gateway is set up: booleans only (test and live configured, self-tests passed, live activated). Never a credential, id or host.

Scope `admin:read`

Effect Read only

MCP tool `get_gateway_status`

Retries Safe to repeat

### Returns

`data`: `GatewayStatus`

Example request Sample

```
curl -X GET "https://api.billingmart.com/v1/admin/gateway-status" \
  -H "Authorization: Bearer $BILLINGMART_API_KEY"
```

Object

## Payment

One payment attempt and its outcome. THE MOST SECURITY-CONSTRAINED DOCUMENT IN THE CONTRACT. PAN and CVV exist only as local variables inside the charging function and appear NOWHERE in this schema — the only card digits persisted are cardLast4 and cardType.

Payment fields
| Field | Type | Notes |
| --- | --- | --- |
| `id`required | `Id` | — |
| `tenant`required | `TenantRef` | — |
| `invoiceId`optional | `Id` | The invoice this payment settles. OPTIONAL: a payment-link payment has none and names `paymentLinkId` instead; exactly one of the two is set. |
| `paymentLinkId`optional | `Id` | The payment link this payment was taken through, when it settles no invoice. |
| `linkCheckoutId`optional | `string` | The checkout (the payer's seat) the payment was made under. |
| `receiptEmail`optional | `string` | M2c: where a payment-link payer asked for the receipt. One address, typed by the payer, used for that ONE receipt and nothing else: it grants no portal, client record, verification or marketing. |
| `clientId`optional | `Id` | — |
| `status`required | `PaymentStatus` | — |
| `method`required | `PaymentMethod` | — |
| `amount`required | `Money` | The amount applied to the invoice. amountDue`, derived from the stored line items at save and send and moved by each ledger posting), so a payment never applies more than is due. |
| `serviceFee`optional | `Money` | The pass-through fee the payer paid on top of `amount` for a card payment, computed once at claim from `amount` and the workspace's rate (integer, half away from zero) and stored, so a replay or a capture never recomput… |
| `serviceFeeBps`optional | `BasisPoints` | The rate `serviceFee` was computed at. |
| `serviceFeeLabel`optional | `ServiceFeeLabel` | — |
| `idempotencyKey`optional | `string` | Identifies one payment ATTEMPT: a retry with the same key replays that attempt and never charges twice. This key plus a time-boxed processing lease are claimed in a transaction before the gateway is touched. |
| `leaseExpiresAt`optional | `IsoTimestamp` | The processing lease. Time-boxed so a crashed attempt cannot wedge an invoice permanently. |
| `gatewayRequestedAt`optional | `IsoTimestamp` | Stamped the moment before the request leaves for the gateway. |
| `cardLast4`optional | `string` | The ONLY card digits ever persisted. |
| `cardType`optional | `string` | — |
| `saveMethodRequested`optional | `boolean` | The customer ticked "save this card" on the pay page after reading the consent copy. A request, not a vault: reads it when it tokenises. Never a card number. |
| `achLast4`optional | `string` | Last four of the account number. The routing number is not persisted. |
| `vaultCustomerId`optional | `string` | Tenant-scoped TranzPay CustomerID. Not a replayable card token. |
| `merchantAccountId`optional | `Id` | The merchant account that took this payment, written by the function that called the gateway. A void, refund or ACH return that arrives later goes to this account, never to whichever account is the default now. |
| `gatewayTransactionId`optional | `string` | — |
| `initiatedBy`optional | `ChargeInitiator` | For a charge of a SAVED method: who started it. Absent on every other payment and on records older than. |
| `gatewayResponse`optional | `GatewayOutcome` | — |
| `pendingReversal`optional | `PendingReversal` | — |
| `failureReason`optional | `string` | Human-readable, already masked. Never the raw gateway body. |
| `settledAt`optional | `IsoTimestamp` | Settlement is POLLED — there are no webhooks. |
| `returnedAt`optional | `IsoTimestamp` | An ACH return, arriving days after the debit. This is what takes an invoice out of `paid`. |
| `returnCode`optional | `string` | The NACHA return code, e.g. R01. |
| `refundedAmount`optional | `Money` | — |
| `doubleCredit`optional | `DoubleCredit` | — |
| `dispute`optional | `PaymentDispute` | PR B: the card dispute on this payment, when the customer's bank disputed it. At most one per payment. Written only by the dispute callables (function-written, like the rest of the payment). |
| `voidAfterReturn`optional | `VoidAfterReturn` | — |
| `recordedBy`optional | `Id` | For cash / check / bankTransfer, the staff uid that recorded it, taken from the verified token. |
| `reference`optional | `string` | Untrusted text For staff-recorded payments: the check number, transfer id or receipt the tenant keeps. With the amount it is the idempotency key of recordOfflinePayment — the same reference and amount twice records one payment. |
| `receiptId`optional | `Id` | The receipt this payment is one allocation of — Receive payment applies one amount across several invoices and writes a payment per invoice, each naming the receipt. |
| `authorization`optional | `PaymentAuthorization` | The customer's authorisation for THIS charge, captured on the pay page before the gateway was called: the sentence they agreed to, the signature they gave, and the request metadata the SERVER observed. |
| `createdAt`required | `IsoTimestamp` | — |
| `updatedAt`optional | `IsoTimestamp` | — |

Object

## PaymentLink

A payment link's CONFIGURATION: what a payer may pay through a shared URL or QR code without an invoice.

PaymentLink fields
| Field | Type | Notes |
| --- | --- | --- |
| `id`required | `Id` | — |
| `tenantId`required | `Id` | — |
| `businessId`optional | `Id` | The business whose name, logo and theme the page shows. Absent: the workspace's first business. |
| `merchantAccountId`optional | `Id` | The merchant account this link takes payments through, fixed when the link is created. Absent means the business default, then the workspace default account. |
| `kind`required | `PaymentLinkKind` | — |
| `preset`required | `PaymentLinkPreset` | — |
| `customName`optional | `string` | Untrusted text The API and MCP return it inside the untrusted-data envelope. |
| `currency`required | `Currency` | — |
| `pricing`required | `PaymentLinkPricing` | — |
| `fixedAmount`optional | `Money` | The price, when `pricing` is `fixed`. |
| `minAmount`optional | `Money` | The least a payer may pay, when `pricing` is `range`. Never below the platform floor ( `PAYMENT_LINK_MIN_MINOR`), which keeps a public any-amount link from testing cards a cent at a time. |
| `maxAmount`optional | `Money` | The most a payer may pay, when `pricing` is `range`. Absent: no upper bound beyond the gateway's. |
| `tiers`optional | `PaymentLinkTier[]` | When `pricing` is `tiered`: the price by payment sequence, `upTo` strictly ascending, the last one no later than `maxPayments`. Payment number n pays the first tier whose `upTo` is at least n. |
| `maxPayments`optional | `integer` | How many payments the link takes in all. Absent: no cap. A one-time link is exactly 1. |
| `displayAvailability`required | `boolean` | Whether the payer's page shows how many remain. Off: the snapshot carries no count at all. |
| `fee`optional | `PaymentLinkFee` | Optional per-link fee the payer pays on top of the price, disclosed before payment and itemised on the receipt. Accepted only on a workspace enabled for fees. |
| `paymentCount`required | `integer` | SERVER-WRITTEN. Payments that succeeded (or ACH payments accepted and not returned). |
| `reservedCount`required | `integer` | SERVER-WRITTEN. Seats held by checkouts whose lease has not ended. |
| `status`required | `PaymentLinkStatus` | — |
| `token`required | `string` | The live public token ( `paymentLinkTokens/{token}`). Rotating it revokes the previous one. |
| `expiresAt`optional | `IsoTimestamp` | Optional: after this the link takes nothing. |
| `configVersion`required | `integer` | Bumped by every edit. A checkout records the version it priced against. |
| `createdAt`required | `IsoTimestamp` | — |
| `createdBy`required | `Id` | The uid from the verified ID token. |
| `updatedAt`required | `IsoTimestamp` | — |
| `updatedBy`required | `Id` | The uid from the verified ID token. |

Object

## PaymentLinkSummary

PaymentLinkSummary is computed by the server for this request, not a stored document, so no contract describes it. Its fields are the TypeScript type of the same name that the handler returns.

Object

## PaymentLinkViews

PaymentLinkViews is computed by the server for this request, not a stored document, so no contract describes it. Its fields are the TypeScript type of the same name that the handler returns.

Object

## PaymentNote

An INTERNAL note on one payment: staff text for the workspace, never shown to the customer and never on a receipt. Read by the members who can read the payment; written ONLY by the `addPaymentNote` callable (and its REST/MCP twin), which takes the author from the verified token and audits it.

PaymentNote fields
| Field | Type | Notes |
| --- | --- | --- |
| `id`required | `Id` | — |
| `tenant`required | `TenantRef` | Copied from the payment, so a member confined to some businesses reads a note exactly when they can read its payment. |
| `paymentId`required | `Id` | — |
| `text`required | `string` | Untrusted text PLAIN TEXT written by a member or a connection; rendered as text, never markup, and returned by the API and MCP inside the untrusted-data envelope. |
| `authorUid`required | `Id` | The member who wrote it, from the verified ID token — never from the payload. |
| `via`optional | `enum` | Where it was written: a person in the console or an app, or a connection (API key or MCP grant) acting for `authorUid`. |
| `credentialId`optional | `Id` | The API key or OAuth grant that wrote it, when `via` is `api`. |
| `createdAt`required | `IsoTimestamp` | — |

Object

## SavedPaymentMethod

A handle on an instrument TRANZPAY HOLDS, not an instrument we hold. THERE IS NOWHERE IN THIS SCHEMA TO PUT A PAN, A CVV, A ROUTING NUMBER OR AN ACCOUNT NUMBER — deliberately, in all three generated languages, so no code can accidentally persist one.

SavedPaymentMethod fields
| Field | Type | Notes |
| --- | --- | --- |
| `id`required | `Id` | — |
| `tenant`required | `TenantRef` | — |
| `clientId`required | `Id` | Whose method this is. A method is never offered to another client, even inside one tenant. |
| `method`required | `PaymentMethod` | `card` or `ach`. 1 trap all over again. |
| `vaultCustomerId`required | `string` | The TranzPay `CustomerID`. CALLER-SUPPLIED, so it is derived from the tenant and the client: re-vaulting the same instrument is idempotent, and the id means nothing in another tenant. |
| `merchantAccountId`optional | `Id` | The merchant account whose vault holds this method. A saved method can be charged only through this account; an invoice routed to another account asks the customer for the card again. |
| `label`optional | `string` | Untrusted text Returned inside the data envelope by every API and MCP response. |
| `cardLast4`optional | `string` | The last four digits: the only part of the card NUMBER ever stored. It sits beside `cardType` and the expiry month and year ( `expMonth`, `expYear`), which are not enough to charge the card. |
| `cardType`optional | `string` | — |
| `expMonth`optional | `integer` | For display and for warning before a card expires. Not a secret, and not enough to charge with. |
| `expYear`optional | `integer` | — |
| `achLast4`optional | `string` | Last four of the account number. THE ROUTING NUMBER IS NOT PERSISTED — together they are the credential that moves money. |
| `bankAccountType`optional | `BankAccountType` | Display only here; the wire builders map it to each operation's own spelling. |
| `consentAt`optional | `IsoTimestamp` | When the customer agreed this method could be kept. Saving a method and permitting a recurring charge on it are two different permissions — the second one is `recurring.autopay.consentAt`. |
| `consentVersion`optional | `string` | Which wording the customer ticked to keep this card. |
| `consentText`optional | `string` | Untrusted text The COMPLETE words of the save-this-card tick, rebuilt by the SERVER from `consentVersion` and the business name; never taken from the client. |
| `consentTextHash`optional | `string` | SHA-256 (hex) of `consentText`, written by the server, so the stored wording can be shown unchanged. |
| `consentClientAt`optional | `IsoTimestamp` | The customer's own clock when they pressed Pay with the tick set. Corroboration beside the authoritative `consentAt` (the server's time), never instead of it. |
| `needsUpdate`optional | `boolean` | Set when a NOC says the bank corrected this account. Nothing keeps silently debiting a corrected account: the method is flagged and a human is told. |
| `needsUpdateCode`optional | `string` | The NOC change code that raised `needsUpdate`, e.g. C01. |
| `lastUsedAt`optional | `IsoTimestamp` | — |
| `archivedAt`optional | `IsoTimestamp` | Archived, never deleted: active is `archivedAt` absent. A payment names the method that paid it, and deleting the method would orphan the record of how money moved. |
| `createdBy`optional | `Id` | From the verified ID token when a staff member saved it; absent when the customer saved it on the pay page. |
| `createdAt`required | `IsoTimestamp` | — |
| `updatedAt`optional | `IsoTimestamp` | — |

Object

## MerchantApplicationSummary

What the applicant's workspace sees of its merchant application after submitting: the status and nothing it submitted, by owner decision. Function-written; owners and admins of the workspace read it; nobody writes it.

MerchantApplicationSummary fields
| Field | Type | Notes |
| --- | --- | --- |
| `id`required | `Id` | — |
| `tenantId`required | `Id` | — |
| `status`required | `MerchantApplicationStatus` | — |
| `dba`required | `string` | Untrusted text The business name, so the list can tell two applications apart. |
| `submittedAt`required | `IsoTimestamp` | — |
| `updatedAt`required | `IsoTimestamp` | — |
| `producerId`optional | `string` | Present once approved. |

Object

## RateRequestSummary

. What the workspace sees of its rate request: the status, the business name, the dates, the platform's quote once given, and the application it became. Function-written; owners and admins of the workspace read it; nobody writes it.

RateRequestSummary fields
| Field | Type | Notes |
| --- | --- | --- |
| `id`required | `Id` | — |
| `tenantId`required | `Id` | — |
| `status`required | `RateRequestStatus` | — |
| `dba`required | `string` | Untrusted text The business name, so the list can tell two requests apart. |
| `submittedAt`required | `IsoTimestamp` | — |
| `updatedAt`required | `IsoTimestamp` | — |
| `passThroughFeesRequested`required | `boolean` | — |
| `quote`optional | `RateQuote` | — |
| `applicationId`optional | `Id` | Present once converted. |

Object

## MerchantAccountView

MerchantAccountView is computed by the server for this request, not a stored document, so no contract describes it. Its fields are the TypeScript type of the same name that the handler returns.

Next section

## Recurring and automation

Schedules that raise invoices on their own, the reminder cadence, and what the scheduled jobs will do next.

[Continue to Recurring and automation →](https://billingmart.com/developers/api/recurring)

## Try it against your sandbox

Create a bmk_test_ key in the console. It can only reach your sandbox workspace.

[Start free](https://app.billingmart.com/sign-up) [All sections](https://billingmart.com/developers/api)

---

This is the Markdown copy of https://billingmart.com/developers/api/payments. Live plans, prices and limits are published as JSON at https://billingmart.com/plans.json and https://billingmart.com/agent-info.json.