Document Requests

When BlueSnap receives a merchant application, our underwriting team initiates a comprehensive Know Your Customer/Anti-Money Laundering (KYC/AML) verification process, which is required by regulators to prevent financial crimes. In some cases, the BlueSnap underwriting team might request documents to verify information about the merchant. If we need more information, we create a document request case in the merchant account. Each document request case is assigned a unique ID and includes a description of the requested documents.

BlueSnap Relay offers multiple ways to manage document requests so you can select the method that best fits your needs:

• Partner-managed requests — With BlueSnap Relay™, you can collect the requested documents from your merchant, then upload the documents and monitor their progress. For comprehensive documentation, see Request Center.
• Document Upload API integration — With BlueSnap Relay™, partners white-label BlueSnap and use our developer tools to respond to document requests. We send an email and APPLICATION_DOCUMENT_REQUEST webhook to notify you about a document request, and we provide the Document Upload API so you can retrieve details about the document request case and upload the requested documents.

After the merchant passes our KYC/AML verification process, we send a welcome email with access to their production account in our global payments network.

Document Upload API

As a partner, you need to know when a document request case is created and how to satisfy the request. BlueSnap uses webhooks and provides the Document Upload API so you can retrieve the document request and then send the requested documents from your partner platform. You can design a merchant-facing site with your branding to collect merchant documents and submit them to BlueSnap underwriting.

The following steps explain how to use information from a BlueSnap webhook to retrieve details about a document request, and then submit the documents to our underwriting team.

Upload Strategy

You need to determine how to manage possible document requests. You have two uploading options:

• On request — BlueSnap sends an APPLICATION_DOCUMENT_REQUEST webhook to inform you that BlueSnap requires additional merchant documentation to complete the underwriting process. You can use the parameter values sent in this webhook to retrieve details about the document request.
• Proactive — If you anticipate that a merchant you plan to onboard requires documents in addition to their merchant application, you can get approval from BlueSnap to proactively upload documents after the merchant application is submitted. After you submit the application, BlueSnap sends the APPLICATION_DOCUMENT_REQUEST webhook immediately. BlueSnap determines which files you can proactively upload based on your business model.

Step 1: Receive a Webhook

BlueSnap sends an APPLICATION_DOCUMENT_REQUEST webhook to inform you that there is a document request case for a merchant:

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

The webhook parameters include important information that you need to send API requests for a specific merchant:

• transactionType — Identifies the webhook as a APPLICATION_DOCUMENT_REQUEST and informs you to start the document upload process.
• sandbox_id — Unique identifier for the merchant's test account. This value is identical to the sandboxId that you received when you submitted the merchant application with your API integration.
• case_id — Unique identifier for the document request.

Store the sandbox_id and case_id values so you can use them in upcoming API requests.

Step 2: Retrieve Document Request Information

You can retrieve details about the document request with the Document Upload API. Send a Retrieve Document Upload request and include as parameters the sandbox_id and case_id values that you received in the APPLICATION_DOCUMENT_REQUEST webhook. These values map to the endpoint's sandboxId and caseId query string parameters. For example:

https://platform.bluesnap.com/services/2/merchants/verification/documents?caseid={case_id}&sandboxid={sandbox_id}

The following example uses sample caseId and sandboxId values:

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

If BlueSnap is ready to receive documents for this request case, you receive a successful response that includes details about the case and the documentation array. The documentation array consists of a list of objects that describe each document request associated with the case:

{
    "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."
        }
    ]
}

This response indicates that BlueSnap is requesting a bank document from the merchant and includes the following properties:

• docType — Indicates BlueSnap requires a bank document
• docGenericDescription — Describes what kinds of bank documents can satisfy this request.

For details about all response properties, see the Responses section in Retrieve Document Upload Request.

📘

Note

If you proactively upload documentation from your merchants and need to add new document type values (docType), please reach out to your Customer Success Manager to update your underwriting settings.

Step 3: Upload Documents to BlueSnap

After you have details about the document request, you must develop a web page that displays these details to your merchant and lets the merchant upload the documents. Provide your merchants as much information about the request as possible — important response values include the following:

• docGenericDescription
• docType
• docUnderwriterNotes

Submit the document

After you customer uploads the document, convert the file contents to a base64-encoded string. Then, send a POST request to the Document Upload API:

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

This request includes the following properties:

• title: Filename of the document that the merchant uploaded.
• fileType: The file's format.
• description: Merchant-provided information about the document that might assist the BlueSnap underwriting team.
• content: Base64-encoded string that contains the file data.

You can send one file per request. For details about all parameters, see Request Content.

{
    "caseId": "5005a00002hJd75AAC",
    "sandboxId": "1156375",
    "docType": "bankDocument",
    "title": "bankcheck.pdf",
    "fileType": "pdf",
    "description": "My Voided Check",
    "content": "SGVsbG8gQmx1ZVNuYXA="
}

A successful request receives a 200 OK response with the "message": "File Uploaded" confirmation in its body:

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

Step 4: Monitor You Webhooks

After you upload your requested documents, listen for webhooks. If BlueSnap requires additional documentation, you receive a APPLICATION_DOCUMENT_REQUEST. If your merchant's application status was updated to process transactions or receive payout, you receive a MERCHANT_PARTNER_ONBOARDED webhook with a merchant ID (MID). For additional information, see Determining Your Status.

Example Documents

BlueSnap might request one of the following types of documents:

• Government-issued photo ID
• Voided check or bank letter
• Business registration documents
• Financial statements
• Processing statements
• Forward delivery schedule
• Website and description of goods-related documents

Government ID Types

This table outlines the accepted Government ID types per country. You must collect this information from your merchant and supply it to BlueSnap in the Create Customer request: