# Fetch Payment Status

Retrieves the per-record processing status of every payment contained in a previously uploaded file. This is the primary reconciliation surface and the source of truth for which individual payments succeeded, which failed, and why. Use it to match DPN results back to internal records, surface errors for remediation, drive payee notifications, and feed downstream systems such as general ledger or audit logs.

Endpoint: GET /payment-files/{file_guid}/payments
Security: securitySchemes.oidcEnforcement

## Security:

  - `securitySchemes.oidcEnforcement` (unknown)
    oauth2

## Path parameters:

  - `file_guid` (string, required)
    Unique tracking number assigned to the payment file at upload. This value is returned in the GUID.trackingNumbers array on the Payment Upload response and is the sole handle used to reference the file on all downstream status and reconciliation calls.

## Query parameters:

  - `pageAfter` (string)
    The start date for filtering payments.

  - `pageBefore` (string)
    The end date for filtering payments.

  - `pageSize` (number)
    The page number for paginated results.

  - `status` (string)
    Filters payments by their status.

## Header parameters:

  - `businessPartner` (string, required)
    Identifier of the disburser submitting the payment file, issued by Deluxe during onboarding. Scopes the request to the correct disburser and routing configuration; this same value must be used on all subsequent status and reconciliation calls for the file.

## Response 200 fields (application/json):

  - `data` (array, required)
    Array of payment records, one per payment in the original file for the current page.

  - `data.guid` (string, required)
    Composite identifier of the form {fileguid}--{paymentId} uniquely identifying a single payment record within the file. Persist this against your internal payment record to enable direct lookup on future calls.
    Example: 3090910c825a48908d616fb55326c4c6--0f786378-ee23-47d2-88a2-8510d680c89e

  - `data.status` (string, required)
    Current status of the individual payment. Common values include Received, Accepted, Processing, InProduction, Completed, and Failed. See the Payment Status Values sections of the integration guide for the full lifecycle catalog per solution.
    Example: Failed

  - `data.deliveryType` (string, required)
    Delivery channel determination for the record once routing has completed. Values include Rejected, Unknown, and workflow-specific values populated as the record progresses.
    Example: Rejected

  - `data.fileDisposition` (integer, required)
    Numeric disposition code assigned by DPN indicating the record's high-level disposition inside the file. Used for internal correlation and support diagnostics.
    Example: 4

  - `data.recordIdentifier` (string, required)
    Caller-supplied identifier carried through from the corresponding row in the uploaded CSV. Use this to correlate the DPN record back to the internal payment record that produced it.
    Example: 50004

  - `data.trackingNumber` (string, required)
    Unique tracking number assigned to this payment file.
    Example: 16f3cc610357b08ff7eeda6d81d91725

  - `data.shipmentMethod` (string)
    Resolved shipment method once routing is determined. Populated when the record progresses far enough for a shipment method to be assigned; null beforehand.

  - `data.createdAt` (string, required)
    Timestamp indicating when DPN first registered the individual payment record. ISO 8601 format.
    Example: 2026-05-08T16:21:46.5794060

  - `data.finishedAt` (string)
    Timestamp indicating when the record reached a terminal state. null while the record is still in progress; populated on terminal success or failure.
    Example: 2026-05-08T16:22:59.0170180

  - `data.errors` (array, required)
    Array of error objects populated when status is Failed. Each entry describes one distinct failure reason and includes enough context for remediation. Empty for records that have not failed.

  - `data.errors.key` (string, required)
    Short identifier for the source of the failure (for example, Destinations) used to categorize the error for reporting.
    Example: Destinations

  - `data.errors.value` (string)
    Value associated with the error key, providing additional context. May be empty when no specific value applies.
    Example: CommercialRouter

  - `data.errors.error` (string, required)
    Human-readable description of the failure. See the Error Messages section of the integration guide for the full catalog of known error messages and their meanings.
    Example: No suitable route could be identified

  - `data.meta` (object, required)
    Object holding metadata for the record.

  - `data.meta.page` (object, required)
    Object holding pagination metadata for the record.

  - `data.meta.page.cursor` (string, required)
    Opaque cursor value used by DPN in the prev and next pagination URLs. Callers should treat this as opaque and pass it back unchanged when paging.
    Example: eyJDcmVhdGVkQXQiOiIyMDI2LTAyLTA1VDE1OjQ0OjU3Ljc1Njg3MjAiLCJJZCI6MjA0MzJ9

  - `links` (object, required)
    Object providing cursor-based pagination URLs for walking large result sets.

  - `links.prev` (string)
    Relative URL for the previous page of results. Absent or null on the first page.
    Example: /v1/payment-files/{fileguid}/payments?pageSize=50&pageBefore=<cursor>

  - `links.next` (string)
    Relative URL for the next page of results. Absent or null on the last page.
    Example: /v1/payment-files/{fileguid}/payments?pageSize=50&pageAfter=<cursor>

## Response 400:

  - `400` (unknown)
    Bad Request

## Response 400 fields (application/json):

  - `error` (object, required)
    error object containing the details of the error.

  - `error.message` (string, required)
    Example: Bad Request

  - `error.details` (string)
    Example: There was an issue with your request message.

## Response 401:

  - `401` (unknown)
    Unauthorized

## Response 401 fields (application/json):

  - `error` (object, required)
    error object containing the details of the error.

  - `error.message` (string, required)
    Example: Bad Request

  - `error.details` (string)
    Example: There was an issue with your request message.

## Response 403:

  - `403` (unknown)
    Forbidden

## Response 403 fields (application/json):

  - `error` (object, required)
    error object containing the details of the error.

  - `error.message` (string, required)
    Example: Bad Request

  - `error.details` (string)
    Example: There was an issue with your request message.

## Response 404:

  - `404` (unknown)
    Not Found

## Response 404 fields (application/json):

  - `error` (object, required)
    error object containing the details of the error.

  - `error.message` (string, required)
    Example: Bad Request

  - `error.details` (string)
    Example: There was an issue with your request message.

## Response 405:

  - `405` (unknown)
    Method Not Allowed

## Response 405 fields (application/json):

  - `error` (object, required)
    error object containing the details of the error.

  - `error.message` (string, required)
    Example: Bad Request

  - `error.details` (string)
    Example: There was an issue with your request message.

## Response 406:

  - `406` (unknown)
    Not Acceptable

## Response 406 fields (application/json):

  - `error` (object, required)
    error object containing the details of the error.

  - `error.message` (string, required)
    Example: Bad Request

  - `error.details` (string)
    Example: There was an issue with your request message.

## Response 408:

  - `408` (unknown)
    Connection Timeout

## Response 408 fields (application/json):

  - `error` (object, required)
    error object containing the details of the error.

  - `error.message` (string, required)
    Example: Bad Request

  - `error.details` (string)
    Example: There was an issue with your request message.

## Response 415:

  - `415` (unknown)
    Unsupported Media Type

## Response 415 fields (application/json):

  - `error` (object, required)
    error object containing the details of the error.

  - `error.message` (string, required)
    Example: Bad Request

  - `error.details` (string)
    Example: There was an issue with your request message.

## Response 429:

  - `429` (unknown)
    Too Many Requests

## Response 429 fields (application/json):

  - `error` (object, required)
    error object containing the details of the error.

  - `error.message` (string, required)
    Example: Bad Request

  - `error.details` (string)
    Example: There was an issue with your request message.

## Response 500:

  - `500` (unknown)
    Internal Server Error

## Response 500 fields (application/json):

  - `error` (object, required)
    error object containing the details of the error.

  - `error.message` (string, required)
    Example: Bad Request

  - `error.details` (string)
    Example: There was an issue with your request message.

## Response 501:

  - `501` (unknown)
    Not Implemented

## Response 501 fields (application/json):

  - `error` (object, required)
    error object containing the details of the error.

  - `error.message` (string, required)
    Example: Bad Request

  - `error.details` (string)
    Example: There was an issue with your request message.

## Response 503:

  - `503` (unknown)
    Service Unavailable

## Response 503 fields (application/json):

  - `error` (object, required)
    error object containing the details of the error.

  - `error.message` (string, required)
    Example: Bad Request

  - `error.details` (string)
    Example: There was an issue with your request message.

