Request a document upload link
Returns an uploadUrl to upload one file to, and a documentId for that file.
Steps
- Call this route.
PUTthe file touploadUrlwithin 30 minutes. See Uploading the file.- Use the
documentId:BusinessDocument: send it inbusinessDocumentIdListon Update business profile.beneficiary: send it indocumentIdson Create beneficiary.payout: send it on the payout it supports.
For BusinessDocument, requesting a link deletes this business's files in the same documentCategory that are still NewDocument: not uploaded yet, or uploaded but not yet through the malware scan. A 200 from the PUT is not enough. Upload one file per documentCategory at a time. (A pending upload that replaces a different rejected document is kept.)
Path
customerIduuidpathrequiredFrom Create business profile. For beneficiary and payout, it can also be your own partner id.
Body
purposestringrequiredBusinessDocument, beneficiary or payout. Not case-sensitive. See upload purposes.
documentCategorystringrequiredBusinessDocument: thedocumentTypeCategoryfrom Get document requirements, for exampleCERTIFICATE_OF_INCORPORATION. To send an extra document that isn't on that list, use any customer-uploadable code from List document types. Up to 100 characters.beneficiaryorpayout:InvoiceorContract.
contentTypestringrequiredThe file's MIME type, in lower case. One of application/, image/, image/, application/, application/, and allowed by the document's allowedFormats. Your PUT must send exactly this Content-Type.
replacesDocumentIduuidBusinessDocument only, optional. When answering a change request: the rejected document this file replaces, from rejectedDocuments in Get verification status. Leave it out and ryno picks the oldest rejected document in this documentCategory that no pending upload already replaces, or the oldest one if all have one. To replace several, request one link per file.
No file name or size is sent. Identity documents for a business's people are not uploaded through the API.
Response
documentIduuidKeep it. You send it in step 3.
uploadUrlstringPresigned URL to PUT the file to.
expiresAtdate-timeWhen uploadUrl stops working (30 minutes).
fileKeystringStorage key, for reference. You don't send it anywhere.
Beneficiary and payout documents
The same route, with these differences:
BusinessDocument | beneficiary / payout | |
|---|---|---|
customerId | A business you onboarded | Your own partner id, or a business you onboarded |
documentCategory | From Get document requirements | Invoice or Contract |
contentType | The document's allowedFormats | PDF, PNG or JPEG |
| Max file size | The document's maxFileSizeMB, at most 10 MB (10,485,760 bytes) | 8 MB (8,388,608 bytes) |
| Once an analyst has the case or has decided | Refused (Customer.) | Allowed |
replacesDocumentId | Allowed | Refused |
| Removes pending uploads in the category | Yes | No |
The document can only be attached to a beneficiary or payout of the customerId it was requested for, and only once its malware scan is clean.
Uploading the file
PUT the raw file bytes to uploadUrl, with the Content-Type header set to exactly the contentType you requested. Send no Authorization header: the link carries it.
- Size is checked after upload. Storage accepts a file over the limit, then deletes it, and the document becomes
Quarantined. Check the size before you upload. - Every file is malware-scanned. Clean files move to
Uploaded. Infected files are deleted and the document becomesQuarantined. - To retry after
Quarantined, request a new link.
Storage returns its own errors, as XML:
| Storage error | HTTP | Cause | Fix |
|---|---|---|---|
SignatureDoesNotMatch | 403 | Content-Type missing or different from contentType, or the URL was changed. | Send the exact contentType; use uploadUrl unchanged. |
AccessDenied (Request has expired) | 403 | The link is older than 30 minutes. | Request a new link. |
Errors
| Code | HTTP | When |
|---|---|---|
ValidationControl. | 400 | A body field is missing or invalid for the purpose. |
Document. | 400 | purpose is missing or unknown. |
Document. | 400 | The document doesn't accept this contentType. |
ComplianceDocumentType. | 400 | documentCategory is neither on the business's requirements nor an active code in List document types. |
ComplianceDocumentType. | 400 | Only compliance staff can attach this document. |
Document. | 400 | replacesDocumentId isn't a rejected document in this category waiting for a replacement. |
Document. | 400 | replacesDocumentId sent with beneficiary or payout. |
Customer. | 404 | BusinessDocument: no customer with this id. |
Customer. | 400 | BusinessDocument: the customer isn't a business. |
Partner. | 403 | You can't upload for this customerId. |
Customer. | 409 | BusinessDocument once an analyst has the case or has decided. Changes requested by compliance can still be answered. |
OnboardingConfig. | 409 | This country needs its own setup first. Contact support. |
DocumentUpload. | 500 | Storage couldn't issue a link. Retry later. Returned as an RFC 7807 problem response. |
See also common errors.