- 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_urlis 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:
filenamemust include an extensionfiletypemust be a supported MIME type for the merchant underwriting document profiledownload_url, when provided, must usehttporhttpsfilenameextension must matchfiletype
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.
Request body for creating a merchant document upload request.
Validation notes:
filenamemust include an extensionfiletypemust be a supported MIME type for the merchant underwriting document profiledownload_url, when provided, must usehttporhttpsfilenameextension must matchfiletype
Merchant document type.
Original filename for the document. The filename must include an extension. For known MIME types, the extension must match filetype.
MIME type for the document. Known MIME types are validated against the filename extension.
- Mock serverhttps://docs.resolvepay.com/_mock/partners-api/openapi/merchants/{merchant_id}/documents
- Sandbox serverhttps://app-sandbox.resolvepay.com/api/merchants/{merchant_id}/documents
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"
}'Successful response with merchant document upload/download initiation details.
Initial validation lifecycle status for the document.
Presigned S3 URL to upload file content when transfer_method is presigned_upload.
Expiration timestamp for upload_url when transfer_method is presigned_upload.
S3 object key where the document is expected to be stored.
How the document is moved into Resolve-managed storage.
Queue dispatch result when transfer_method is download_url.
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_domainx-amz-meta-callback_url
{ "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" }
{ "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" }