Skip to content

Create a Merchant Document Upload Request

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.

Security
bearerAuth or basicAuth
Path
merchant_idstringrequired

ID of the sub-merchant under your partner account.

Example:mrc_1234567890abcdef
Bodyapplication/jsonrequired

Request body for creating a merchant document upload request.

Validation notes:

  • 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
document_typestringrequired

Merchant document type.

Enum:"bank_statements""financial_statements""credit_references""personal_guarantee""other"
Example:"bank_statements"
filenamestringrequired

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

Example:"bank_statement_2026_01.pdf"
filetypestringrequired

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

Example:"application/pdf"
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:"https://partner-files.example.com/bank_statement_2026_01.pdf"
curl -i -X POST \
  https://docs.resolvepay.com/_mock/partners-api/openapi/merchants/mrc_1234567890abcdef/documents \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "document_type": "bank_statements",
    "filename": "bank_statement_2026_01.pdf",
    "filetype": "application/pdf"
  }'

Responses

Successful response with merchant document upload/download initiation details.

Bodyapplication/json
idstring

Unique identifier of the merchant document.

Example:"md_1234567890abcdef"
document_idstring

Alias of the merchant document identifier.

Example:"md_1234567890abcdef"
document_typestring
Enum:"bank_statements""financial_statements""credit_references""personal_guarantee""other"
Example:"bank_statements"
statusstring

Initial validation lifecycle status for the document.

Enum:"pending_upload""failed"
Example:"pending_upload"
upload_urlstring or null, (uri)

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

Example:"https://resolve-document-validation-uploads-dev.s3.amazonaws.com/merchant/mrc_123/document/md_123/bank_statement_2026_01.pdf?X-Amz-Algorithm=AWS4-HMA
upload_expires_atstring or null, (date-time)

Expiration timestamp for upload_url when transfer_method is presigned_upload.

Example:"2026-02-26T18:35:00.000Z"
object_keystring

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

Example:"merchant/mrc_123/document/md_1234567890abcdef/bank_statement_2026_01.pdf"
transfer_methodstring

How the document is moved into Resolve-managed storage.

Enum:"presigned_upload""download_url"
Example:"presigned_upload"
queue_dispatch_statusstring or null

Queue dispatch result when transfer_method is download_url.

Enum:"queued""failed"
Example:"queued"
upload_headersobject or null

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
Example:
{ "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_profilestring

Resolve-managed document validation profile applied to this request.

Value:"merchant_underwriting_document_default"
Example:"merchant_underwriting_document_default"
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": null, "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" }