# Fetch Payment File Status

Retrieves the aggregate processing status of a previously uploaded payment file, including total record count, counts of completed and failed records, and the current file-level status. Use this endpoint to monitor a submitted batch through its lifecycle without pulling per-record detail; it is typically invoked on a polling cadence until the file reaches a terminal state.

Endpoint: GET /payment-files/{file_guid}
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.

## 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` (object, required)
    Object holding the file-level status snapshot.

  - `data.trackingNumber` (string, required)
    The fileguid echoed back from the request path, confirming which file the response describes.
    Example: 3090910c825a48908d616fb55326c4c6

  - `data.createdAt` (string, required)
    Timestamp indicating when DPN first received and registered the payment file. Expressed in ISO 8601 format.
    Example: 2026-05-08T16:21:43.127224

  - `data.recordCount` (integer, required)
    Total number of payment records contained in the uploaded file, as counted by DPN after successful ingestion. This is the denominator against which completedCount and failedCount should be reconciled.
    Example: 7

  - `data.fileName` (string, required)
    Original filename of the uploaded CSV, as supplied by the caller on the Payment Upload request.
    Example: DPN_Payment_Test_File_20260311.csv

  - `data.uploadType` (string, required)
    Indicates how the file was submitted to DPN. HTTP denotes an API upload via the Payment Upload endpoint; other values may appear when the file arrives through alternate channels such as SFTP.
    Example: HTTP

  - `data.completedCount` (integer, required)
    Number of payment records in the file that have reached a terminal successful state at the time of the query. Compare against recordCount and failedCount to determine remaining in-flight work.
    Example: 0

  - `data.failedCount` (integer, required)
    Number of payment records in the file that have reached a terminal failed state at the time of the query. A non-zero value signals that the caller should drill into the Payment Status endpoint to retrieve the specific error detail per failed record.
    Example: 5

  - `data.status` (string, required)
    Aggregate file-level status. Incomplete indicates the file is still being processed; terminal values such as Complete and Failed indicate that DPN has finished processing the file. Confirm the complete set of terminal states with Deluxe as part of onboarding.
    Example: Incomplete

  - `links` (object, required)
    Object providing convenience URLs for related resources.

  - `links.self` (string, required)
    Relative URL of the current resource, provided for HATEOAS-style navigation.
    Example: /v1/payment-files/3090910c825a48908d616fb55326c4c6

  - `links.payments` (string, required)
    Relative URL of the per-record payments resource for this file. Follow this link to retrieve individual payment statuses via the Payment Status endpoint.
    Example: /v1/payment-files/dcd84961c29a1223740af2669daa7e52/payments

## 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.

