Skip to content
Merchant API/
/
Upload a customer support...

Upload a customer supporting document

Request

Attaches a supporting document to a customer and starts its transfer into Resolve's document validation service. Use this to hand Resolve buyer data you already hold — bank statements, financial statements, credit references, or payment history — so it can be used in a credit decision.

Create the customer first; this endpoint is separate from customer creation and belongs to the merchant v5 API. MCP clients use create_customer_document with the returned customer ID as merchant_customer_id. In ChatGPT, attach the file as download_url and supply filename and filetype separately. See the Merchant MCP tool reference.

The transfer mode is determined by the request shape:

  • Omit download_url and Resolve returns a presigned S3 upload_url (transfer_method=presigned_upload). PUT the document bytes to that URL with the headers in upload_headers before upload_expires_at.
  • Supply download_url and Resolve queues a background download job (transfer_method=download_url). There is nothing to upload.

Documents are validated asynchronously, so a successful response means the document was accepted for transfer, not that it passed validation. Poll #fetchCustomer for the resulting credit_status and limit changes; these are not per-document validation status.

Fulfilling a banking-data request. When a credit decision is waiting on bank statements, pass the open request's ID as additional_data_request_id alongside a bank_statements upload. Resolve fulfills that request once the document validates. The field is only accepted with document_type bank_statements, and is rejected with 422 if it does not identify a banking-data request on this customer that is still awaiting a response.

Validation notes:

  • bank_statements must be PDFs; other document types also accept PNG, JPEG, CSV, XLS, and XLSX
  • filename must include an extension matching filetype
  • download_url, when provided, must use http or https, carry no embedded credentials, and resolve to a public host

For remote downloads, queue dispatch runs after the document row is committed. A dispatch failure at that point does not roll the document back — the response is still successful and queue_dispatch_status comes back as failed.

Security
bearerAuth or basicAuth
Path
customer_idstringrequired

Customer relationship ID returned by the merchant Customers API.

Bodyapplication/jsonrequired

The supporting document to attach to the customer.

The transfer mode is determined by the request shape:

  • Omit download_url and Resolve returns a presigned S3 upload URL for you to PUT the bytes to.
  • Supply download_url and Resolve queues a background job to fetch the document from your host.

Validation notes:

  • filename must include an extension, and for known MIME types that extension must match filetype
  • document_type bank_statements is restricted to application/pdf
  • additional_data_request_id is only accepted when document_type is bank_statements
  • download_url, when provided, must use http or https and resolve to a public host
  • Unknown fields are rejected with 400
One of:

Requests a presigned upload URL for a PDF bank statement. Omit download_url and PUT the document bytes to the upload_url returned in the response.

document_typestringrequired

The type of supporting document being uploaded.

Value:"bank_statements"
Example:"bank_statements"
additional_data_request_idstring

Optional open banking-data additional data request to fulfill. Must reference an additional data request on this customer with request_type banking_data that is still awaiting a response — anything else is rejected with 422.

This field is only accepted when document_type is bank_statements.

Example:"adr_1234567890abcdef"
filenamestring\.[pP][dD][fF]$required

Filename including a .pdf extension.

Example:"bank_statement_2026_01.pdf"
filetypestringrequired

Bank statements must be uploaded as PDFs.

Value:"application/pdf"
Example:"application/pdf"
curl -i -X POST \
  'https://docs.resolvepay.com/_mock/merchant-api/openapi/customers/{customer_id}/documents' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "document_type": "bank_statements",
    "additional_data_request_id": "adr_1234567890abcdef",
    "filename": "bank_statement_2026_01.pdf",
    "filetype": "application/pdf"
  }'

Responses

Upload instructions for the customer document. The shape depends on the transfer mode requested.

Bodyapplication/json
One of:

Returned when the request omits download_url. Upload the document by issuing a PUT to upload_url with the headers in upload_headers before upload_expires_at.

idstringrequired

Unique identifier of the customer document.

Example:"mcd_1234567890abcdef"
document_idstringrequired

Alias of the customer document identifier.

Example:"mcd_1234567890abcdef"
document_typestringrequired
Enum:"bank_statements""credit_references""financial_statements""payment_history""other"
Example:"bank_statements"
upload_urlstring, (uri)required

Presigned S3 URL to PUT the document bytes to.

Example:"https://resolve-document-validation-uploads.s3.amazonaws.com/merchant_customer/cus_123/document/mcd_123/bank_statement_2026_01.pdf?X-Amz-Algorithm=AW
upload_expires_atstring, (date-time)required

Expiration timestamp for upload_url.

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

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

Example:"merchant_customer/cus_1234567890abcdef/document/mcd_1234567890abcdef/bank_statement_2026_01.pdf"
transfer_methodstringrequired

How the document is moved into Resolve-managed storage.

Value:"presigned_upload"
Example:"presigned_upload"
queue_dispatch_statusstring or nullrequired

Always null for presigned uploads. Only remote-URL requests dispatch a download job.

Value:null
Example:null
upload_headersobjectrequired

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"
}
validation_profilestringrequired

Validation profile Resolve applies to the document. Managed by Resolve and not overridable.

Value:"merchant_underwriting_document_default"
Example:"merchant_underwriting_document_default"
Response
{
  "id": "mcd_1234567890abcdef",
  "document_id": "mcd_1234567890abcdef",
  "document_type": "bank_statements",
  "upload_url": "https://resolve-document-validation-uploads.s3.amazonaws.com/merchant_customer/cus_123/document/mcd_123/bank_statement_2026_01.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&...",
  "upload_expires_at": "2026-02-26T18:35:00.000Z",
  "object_key": "merchant_customer/cus_1234567890abcdef/document/mcd_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"
  },
  "validation_profile": "merchant_underwriting_document_default"
}