Document Upload APIs

The Document Upload API suite allows you to fully automate your KYC workflows with BlueSnap. Using these endpoints, you can proactively submit underwriting documentation and build out a merchant-facing experience for your customers to get approved, all behind your brand.

Notifications

There are two notification types that can trigger the same workflow:

• Proactive Document Upload Notifications: Notifications will be triggered within moments of merchant creation. Note that prior approval from BlueSnap is required to use this workflow. BlueSnap will determine which files can be passed in based on your business model.
• Respond to Underwriting Requests Notifications: Notifications are triggered at the time of underwriting review.

Workflow

Step 1: Receive Webhook from BlueSnap

Listen for an APPLICATION_DOCUMENT_REQUEST notification:

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

The notification also contains the sandbox_id and case_id. The sandbox_id value identifies the customer associated with this application document request—it is the same value as the sandboxId that you received in the response for the Create Merchant POST request. The case_id identifies the application document request.

Step 2: Send a Retrieve Documents Request and provide details to your customer

Send a Retrieve Documents API request to get the most recent information about the application document request:

https://platform.bluesnap.com/services/2/merchants/verification/documents

This request does not require a request body. Instead, use the case_id and sandbox_id from the previous step as the caseid and sandboxid query parameters in the request:

https://platform.bluesnap.com/services/2/merchants/verification/documents?caseid=5005a00002kAF6sAAG&sandboxid=1165743

Response Details

If successful, the response HTTP status code is 200 OK. The response contains the retrieved documentation array and includes real-time details.

documentation object

Examples

Request Example

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=' \
-d '

Response Example

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

Your customer (merchant applicant) needs to know which docTypes have been requested. If you are using Proactive Document Upload Notifications, these definitions will be the same for all your merchants. If our underwriting team requests a docType, all merchants will see it listed in the GET response.

When customers access your platform, they should be shown requirements with as much detail as possible. We recommend displaying the real-time docGenericDescription and docType. If docUnderwriterNotes is present in the GET response, you should also display this parameter.

Key Points for the Retrieve Documents API Request

• Receiving a successful GET response signals that you are ready to upload documents using the Document Upload request (as long as the docLimit has not been reached).
• If you are proactively gathering documentation from your merchants and need to add docTypes, please reach out to your Customer Success Manager so we can update your underwriting settings.

Step 3: Provide your customer the ability to upload files to BlueSnap

Use the Document Upload API request detailed below to provide a document upload experience. The user can upload a file and convert it to Base64 encrypted string. This encrypted string will be the value of the content parameter. Define the title parameter using the filename of the file the customer uploads. You can parse the fileType from what they provide. You can include a field to populate the description parameter with customer notes for our underwriting team. Submit POST requests (one per file), with the B64 string. Display Success to your customer after all operations are complete. Optional: Send a subsequent GET to ensure the applicable ‘status’ variables have updated from “Requested” to “Received”.

File Requirements

• The file size can not exceed 10MB
• Include only one file per request
• Valid fileType values:
  • pdf
  • jpg/jpeg
  • png
  • pdf
  • tif/tiff
  • xls
  • xlsx
  • jpg
  • jpeg

Document Upload API Request

https://platform.bluesnap.com/services/2/merchants/verification/documents

Request Content

The request content includes parameters from the Retrieve Documents API Request response as well as the defining attributes of the document being submitted.

Response Details

If successful, the response HTTP status code is 200 OK and it contains the message "File Uploaded”.

Examples

Request Example

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

Response Example

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

Key Points for Automation

• The Merchant Partner Onboarded webhook indicates that your application has been received and is being processed.
• The Application Document Request webhook indicates that one of the following has occurred:
  • Our risk screening engine is ready to receive documents that have been collected.
  • Our underwriting team has a new request for you.
• You can only upload documents listed in the Retrieve Documents API response details.