Skip to main content

Create a File Resource

Suggest Edits

Overview​

Create a File resource before uploading the actual file content. This is a two-step process: first create the file metadata using this endpoint, then upload the actual file content to the /files/\{file_id}/upload endpoint. Files are commonly used for merchant onboarding documentation such as bank statements, tax documents, and PCI compliance documents.

Resource Access​

Production (api.ahrvo.network)

POST https://api.ahrvo.network/payments/na/files

Staging (gateway.ahrvo.network)

POST http://gateway.ahrvo.network/payments/na/files

Arguments​

AttributeMandatory / OptionalDescription
display_nameMandatoryUser-friendly name for the file
linked_toMandatoryThe ID of the Merchant or Application the file is linked to
typeMandatoryThe type of file (BANK_STATEMENT, PCI_DOCUMENT, TAX_DOCUMENT)
tagsOptionalKey-value metadata to attach to the file

Example Request​

curl -X POST https://gateway.ahrvo.network/payments/na/files \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <base64_encoded_credentials>" \
  -d '{
    "display_name": "Bank Statement (December 2025)",
    "linked_to": "MRxxxxxxxxxxxxxxxxxx",
    "type": "BANK_STATEMENT",
    "tags": {
      "month": "2025-12",
      "purpose": "merchant_onboarding"
    }
  }'

Example Response​

{
  "id": "FIxxxxxxxxxxxxxxxxxx",
  "status": "REQUIRES_UPLOAD",
  "created_at": "2025-12-10T17:00:00Z",
  "updated_at": "2025-12-10T17:00:00Z",
  "linked_type": "MERCHANT",
  "linked_to": "MRxxxxxxxxxxxxxxxxxx",
  "extension": null,
  "display_name": "Bank Statement (December 2025)",
  "type": "BANK_STATEMENT",
  "size_in_bytes": null,
  "file_name": null,
  "tags": {
    "month": "2025-12",
    "purpose": "merchant_onboarding"
  },
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/files/FIxxxxxxxxxxxxxxxxxx"
    },
    "upload": {
      "href": "https://api.ahrvo.network/payments/na/files/FIxxxxxxxxxxxxxxxxxx/upload"
    }
  }
}

File Types​

The following file types are supported:

  • BANK_STATEMENT: Bank statements for merchant verification
  • PCI_DOCUMENT: PCI compliance documentation
  • TAX_DOCUMENT: Tax-related documents (W9, EIN verification, etc.)

File Status Values​

  • REQUIRES_UPLOAD: File resource created but content not yet uploaded
  • PENDING: File uploaded and being processed
  • UPLOADED: File successfully uploaded and processed

Next Steps​

After creating the file resource:

  1. Note the file_id from the response
  2. Use the /files/\{file_id}/upload endpoint to upload the actual file content
  3. The status will change from REQUIRES_UPLOAD to PENDING and then UPLOADED

API Documentation​