REresolvepay
Merchants

Create a Merchant Document Upload Request

Creates a new merchant document record for a sub-merchant and initializes document transfer to the Resolve document validation service.

The transfer method is determined by request shape:

  • If download_url is provided, Resolve queues a background download job (transfer_method=download_url).
  • Otherwise, Resolve returns a presigned S3 upload URL (transfer_method=presigned_upload).

The validation profile is endpoint-managed by Resolve and cannot be overridden in the request.

Request validation includes:

  • filename must include an extension
  • filetype must be a supported MIME type for the merchant underwriting document profile
  • download_url, when provided, must use http or https
  • filename extension must match filetype

For download_url, queue dispatch is executed after database commit. A dispatch failure at that stage does not roll back the merchant document row; instead, the response remains successful and the document is marked failed.

post/merchants/{merchant_id}/documents

Request

Path parameters

merchant_idstring required

ID of the sub-merchant under your partner account.

Request body

document_type'bank_statements' | 'financial_statements' | 'credit_references' | 'personal_guarantee' | 'other' required

Merchant document type.

filenamestring required

Original filename for the document. The filename must include an extension. For known MIME types, the extension must match filetype.

filetypestring required

MIME type for the document. Known MIME types are validated against the filename extension.

download_urlstring uri

Optional remote URL for Resolve to fetch directly. When provided, Resolve queues a background download job and does not return a presigned upload URL. Only http and https URLs are accepted.

Example request

{
  "document_type": "bank_statements",
  "filename": "bank_statement_2026_01.pdf",
  "filetype": "application/pdf",
  "download_url": "https://partner-files.example.com/bank_statement_2026_01.pdf"
}

Response

Successful response with merchant document upload/download initiation details.

idstring

Unique identifier of the merchant document.

document_idstring

Alias of the merchant document identifier.

document_type'bank_statements' | 'financial_statements' | 'credit_references' | 'personal_guarantee' | 'other'
status'pending_upload' | 'failed'

Initial validation lifecycle status for the document.

upload_urlstring uri nullable

Presigned S3 URL to upload file content when transfer_method is presigned_upload.

upload_expires_atstring date-time nullable

Expiration timestamp for upload_url when transfer_method is presigned_upload.

object_keystring

S3 object key where the document is expected to be stored.

transfer_method'presigned_upload' | 'download_url'

How the document is moved into Resolve-managed storage.

queue_dispatch_status'queued' | 'failed' nullable

Queue dispatch result when transfer_method is download_url.

upload_headersobject nullable

Required headers to include on the presigned upload PUT request.

Always includes:

  • x-amz-meta-validation_profile

May include callback routing headers when configured by Resolve:

  • x-amz-meta-callback_domain
  • x-amz-meta-callback_url
validation_profile'merchant_underwriting_document_default'

Resolve-managed document validation profile applied to this request.

Example response

{
  "id": "md_1234567890abcdef",
  "document_id": "md_1234567890abcdef",
  "document_type": "bank_statements",
  "status": "pending_upload",
  "upload_url": "https://resolve-document-validation-uploads-dev.s3.amazonaws.com/merchant/mrc_123/document/md_123/bank_statement_2026_01.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&...",
  "upload_expires_at": "2026-02-26T18:35:00.000Z",
  "object_key": "merchant/mrc_123/document/md_1234567890abcdef/bank_statement_2026_01.pdf",
  "transfer_method": "presigned_upload",
  "queue_dispatch_status": "queued",
  "upload_headers": {
    "x-amz-meta-validation_profile": "merchant_underwriting_document_default",
    "x-amz-meta-callback_domain": "overcommunicative-unriotously-alaina.ngrok-free.dev",
    "x-amz-meta-callback_url": "https://overcommunicative-unriotously-alaina.ngrok-free.dev/api/internal/document-validation/completed"
  },
  "validation_profile": "merchant_underwriting_document_default"
}

Changes

No recorded changes to this operation across all 1 revision of this API.