Marketplace Document Upload API

The Marketplace Document Upload API suite allows you to fully automate your KYC workflows with BlueSnap.
Using these endpoints, you can build out a customer-facing experience for your vendors to get approved, all behind your Marketplace brand.

Workflow

• Step 1: Receive IPN from BlueSnap
• Step 2: Send a Retrieve Documents Request and provide details to your customer
• Step 3: Provide your customer the ability to upload files to BlueSnap

Step 1: Receive IPN from BlueSnap

Listen for notifications with transactionType= APPLICATION_DOCUMENT_REQUEST. This notification contains the vendor_id and case_id. The vendor_id is also included in the webhook you receive after creating the vendor. This will be your key for association to inform your customer they have action to take.

For example:

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

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

Once you receive the notifications, take the values provided and send a Retrieve Documents API request. This ensures you have the latest information at the time of processing the request to show your vendor what to upload.

Retrieve Documents API Request

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

Request Content

No content is required in the request body. Enter the relevant IDs in the request URL, as follows:

https://ws.bluesnap.com/services/2/vendors/verification/documents?caseid=500UO000002Bt9lYAC&vendorid=1349418

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://ws.bluesnap.com/services/2/vendors/verification/documents?caseid=5005a00002kAF6sAAG&vendorid=1350200 \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '

Response Example

{
    "caseStatus": "Document request pending",
    "caseId": "5005a00002kAF6sAAG",
    "vendorId": " 1350200",
    "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."
        }
    ]
}

When vendors 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).
• You can only upload documents that are listed in the GET response details.

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. If desired, you can allow your vendor to provide a description. Submit POST requests (one per file), with the B64 string. Display Success to your vendor after all operations are complete. Optional: Send a subsequent GET to ensure the applicable ‘status’ variables have updated from “Requested” to “Received”. If the docsRecieved value is lower than docLimit, you can still upload more documents for a docType that has a status of “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://ws.bluesnap.com/services/2/vendors/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",
    "vendorId": "1156375",
    "docType": "bankDocument",
    "title": "bankcheck.pdf",
    "fileType": "pdf",
    "description": "My Voided Check",
    "content": "SGVsbG8gQmx1ZVNuYXA="
}

Response Example

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