Get Payment By ID
This allows the user to retrieve a payment using it's id.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| id | Int | Yes | N/A | The payment's ID found in your Checkissuing dashboard or in the payment's information returned from various API calls |
| include_tracking | Boolean | No | false |
Pass true to include the metadata.tracking_data object (with
tracking_number, carrier_id, carrier_code, and
carrier_service) on the returned payment. When omitted or false, the
tracking_data object is not added to metadata. The legacy
metadata.tracking string (tracking number only) is always returned when the payment
has a tracking number on file, regardless of this flag.
|
| include_audit | Boolean | No | false |
Set to true to embed the payment audit history as
payment.audit. Omitting this parameter leaves the existing response contract
unchanged. |
Audit History Inclusion
Use GET /payments/by-id/{id?}?include_audit=true or include include_audit=true
in the existing POST /payments/by-id request to include the payment's audit history in the
response.
| Field | Type | Description |
|---|---|---|
| payment.audit.total_events | Int | Total number of audit events returned for the payment. |
| payment.audit.events | Array | Audit events returned newest first. If no records exist, this is an empty array. |
| event_id | Int | Unique audit event ID. |
| type | String | Audit event type, such as created, updated,
sent, or delivered. |
| timestamp | String | ISO 8601 UTC timestamp, for example 2024-03-14T11:32:00Z. |
| actor | String | User name/email or system actor that performed the event. |
| description | String | Short audit description for display and reconciliation. |
| metadata | Object | Optional audit metadata associated with the event. |
If no audit records exist, payment.audit is {"total_events":0,"events":[]}. If
audit history is temporarily unavailable, the payment still returns with HTTP 200 and
payment.audit is {"error":"audit_service_unavailable"}.
Future v2 pagination guidance: this v1 parameter embeds the complete audit history for backward
compatibility. If paginated audit history is introduced in a v2 API, clients should move to the v2
paginated audit endpoint while treating include_audit=true as the legacy compatibility path.
Sample Response
{"status":0,"errors":[],"error_message":"","payment":{"id":"1","payee_id":null,"account_id":null,"client_invoice_id":null,"file_id":null,
"batch_id":null,"status_id":"2","postage_id":null,"guid":"c4ca4238a0b923820dcc509a6f75849b","created_ts":"2019-09-22 05:46:05","updated_ts":null,"deleted_ts":null,
"issue_ts":null,"sent_ts":null,"cancelled_ts":null,"returned_ts":null,"cleared_ts":null,"claimed_ts":null,"payee_name":"A Payee","payee_address":"123 Some St. City, ST 33434",
"memo":null,"amount":"100.00","fees":"0.00","flagged":"0","confirmed":"1","claimed":"0","is_digital":"0","deleted":"0",
"metadata":{"tracking":"9400110200881234567890","tracking_data":{"tracking_number":"9400110200881234567890","carrier_id":1,"carrier_code":"USPS","carrier_service":"USPS_PRIORITY"}}}}
Tracking Fields
The legacy metadata.tracking string (just the carrier tracking number) is returned
unconditionally whenever the payment has a tracking number on file — this is the same field
long-standing integrations have always consumed. The richer metadata.tracking_data object
(carrier id, code, and service) is opt-in: pass include_tracking=true to receive it. When
include_tracking is omitted, the tracking_data object is not added to the
metadata object. Neither field is returned at the top level of the payment.
When a payment belongs to a bundle and the bundle has tracking assigned, that tracking is
automatically mirrored onto each payment in the bundle, so every payment in the bundle returns the
same tracking_number, carrier_code, and carrier_service as the
bundle. Payments that already have their own individually-assigned tracking keep that override.
| Field | Type | Description |
|---|---|---|
| metadata.tracking | String / absent | Legacy scalar mirror of the active tracking number. Always returned when the payment has any
tracking number on file (resolved in the same order as tracking_data); omitted from
the metadata object when no tracking number is known. This field is independent of
the include_tracking flag. |
| metadata.tracking_data | Object | Container object for the tracking sub-fields below. Only present when
include_tracking=true is passed.
|
| metadata.tracking_data.tracking_number | String / null | Carrier tracking number for the payment's mailpiece, or null when not yet assigned.
|
| metadata.tracking_data.carrier_id | Integer / null | ID of the tracking carrier stored on the active tracking record. null when only a
legacy tracking number is known. |
| metadata.tracking_data.carrier_code | String / null | Short carrier code (e.g. USPS, FEDEX, UPS,
DHL,
OTHER) for the active tracking record. When the tracking row has no carrier we fall
back to the carrier implied by the payment's postage (or the bundle's postage for inherited
tracking).
|
| metadata.tracking_data.carrier_service | String / null | Normalized carrier-service code for the active tracking record (e.g.
USPS_PRIORITY, FEDEX_2DAY, UPS_GROUND). null
when no service is set.
|
Resolution order (used for both metadata.tracking and
metadata.tracking_data): (1) the payment's own tracking record; (2) legacy metadata
tracking value (number only); (3) the bundle's tracking record when the payment belongs to a bundle;
(4) the legacy bundle tracking column (number only). The first non-empty source wins.
Sample Response with include_audit=true
{"status":1,"errors":[],"error_message":"","payment":{"id":"1","amount":"100.00","currency":"USD","status_id":"2","audit":{"total_events":1,"events":[{"event_id":192,"type":"delivered","timestamp":"2024-03-14T11:32:00Z","actor":"system","description":"Confirmed receipt at beneficiary bank","metadata":{"reference":"TRN-44821"}}]}}}