Platform-Managed Requests

With platform-managed document requests, your platform collects documents from the merchant in your own experience and uploads them to BlueSnap using the Document Upload API.

Use this option when you want a white-labeled onboarding flow and do not want BlueSnap to collect documents directly from the merchant.

Document Request Process

Watch this onboarding demonstration for an example of the document request process.

In this workflow, your platform owns merchant-facing document collection. Your platform receives the document request, shows the request to the merchant, collects the files, and uploads them to BlueSnap by API.

1. BlueSnap sends an APPLICATION_DOCUMENT_REQUEST webhook.
2. Your platform stores the case_id and sandbox_id from the webhook.
3. Your platform retrieves the document request details from BlueSnap.
4. Your platform shows the requested documents to the merchant in your own UI.
5. The merchant uploads the files in your platform, which then uploads each file to BlueSnap.
6. Your platform monitors onboarding status through webhooks.

1. Receive the Document Request Webhook

BlueSnap sends an APPLICATION_DOCUMENT_REQUEST webhook when additional documents are required. This webhook means BlueSnap needs more information to complete the merchant’s KYC/AML review. It does not mean the merchant was declined.

transactionType=APPLICATION_DOCUMENT_REQUEST
&sandbox_id=1165743
&case_id=5005a00002kAF6sAAG
&ipnId=937b8a9a-a31f-48b1-8db6-9b5a331d5c9

2. Store Important Values

Store the following values from the webhook:

3. Retrieve the Document Request

Use the case_id and sandbox_id from the webhook to get details about the requested documents from the Retrieve Document Request API.

curl -v -X GET "https://platform.bluesnap.com/services/2/merchants/verification/documents?caseid=5005a00002kAF6sAAG&sandboxid=1165743" \ 
-H "Accept: application/json" \ 
-H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ="

{
  "caseStatus": "Document request pending",
  "sandboxId": "1165743",
  "caseId": "5005a00002kAF6sAAG",
  "documentation": [
    {
      "status": "Requested",
      "docUnderwriterNotes": null,
      "docType": "bankDocument",
      "docsReceived": null,
      "docLimit": 2,
      "docGenericDescription": "A voided check from your financial institution, or a bank letter confirming Legal Entity association with the bank number provided. Temporary checks will not be accepted, and bank letters must be on bank letterhead."
    }
  ]
}

Use the response to determine which documents are required and what instructions to show to the merchant.

4. Show Request to the Merchant

After retrieving the request, display the relevant document details from the response in your merchant-facing UI. Useful fields may include:

5. Upload Documents

After the merchant uploads a file in your UI, convert the file contents to a Base64-encoded string and send the document to BlueSnap via the Create Document Upload API. You can upload one file per request, which must not exceed 10MB in size.

curl -v -X POST "https://platform.bluesnap.com/services/2/merchants/verification/documents" \ 
-H "Content-Type: application/json" \ 
-H "Accept: text/plain" \ 
-H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=" \ 
-d '
{ 
  "caseId": "5005a00002hJd75AAC",
  "sandboxId": "1156375", 
  "docType": "bankDocument", 
  "title": "bankcheck.pdf", 
  "fileType": "pdf", 
  "description": "Voided check", 
  "content": "SGVsbG8gQmx1ZVNuYXA=" 
}'

{ 
  "status": "success", 
  "message": "File Uploaded" 
}

Proactive Document Uploads

BlueSnap supports proactive document uploads for approved platforms when enabled for your configuration.

BlueSnap determines which document types your platform can upload proactively based on your business model and underwriting configuration. Use proactive uploads when your platform already collects standard documents from merchants and wants to reduce the chance of follow-up requests during underwriting. To keep the initial onboarding flow lighter, collect documents only after BlueSnap requests them. This approach helps avoid asking merchants for documents that BlueSnap may not need.

6. Monitor Status

After you upload documents, continue listening for webhooks. BlueSnap may send another APPLICATION_DOCUMENT_REQUEST webhook if more documents are required.

If the merchant is approved, BlueSnap sends the relevant onboarding webhook with the merchantId.

Tips to Reduce Onboarding Delays

To reduce onboarding delays:

• Show the merchant the docGenericDescription and any docUnderwriterNotes.
• Validate file type before upload.
• Limit uploads based on the docLimit value.
• Use clear file names.
• Include a helpful description with each upload.
• Store the case_id and sandbox_id from the webhook.
• Continue monitoring onboarding status after each upload.