What you’ll build
By the end of this guide, your system will be able to:- Upload a receipt file and wait for its malware scan.
- Attach it to a card transaction.
- List, download and delete the receipts on a transaction.
How it works
Before you begin
- A team administrator has created an API key with
card_activities:readandcard_activities:write. See Authentication. - You have the
idof a card transaction from List card activities.
Steps
1
Upload the file
Send a We check the file type from its content, not its name. A file that isn’t a PDF, JPEG, PNG, GIF or HEIC returns
multipart/form-data request. Put purpose=card_receipt before the file field.422 FILE_TYPE_NOT_SUPPORTED. A file over 10 MB returns 413.If the upload returns 503, we couldn’t store the file right now. Wait a few seconds, then upload it again. If you retry automatically, back off exponentially with jitter and stop after a few tries. A retried upload can leave an unused file behind, which expires on its own. Upload retries don’t need an Idempotency-Key; that header is only for attaching the file.2
Wait until the file is ready
- Call it every 2 to 5 seconds until
statusisready. This can take up to 5 minutes. blockedorfailedmeans the file can’t be used. Upload a different one.
3
Attach it to the transaction
201 with the receipt.4
Retry safely
If the request returns
502 or ATTACH_IN_PROGRESS, we couldn’t confirm the receipt. Send the same request again every minute, for up to 10 minutes. It never makes a second receipt. Use a new Idempotency-Key for each transaction and file.Each file can be attached once. Attaching it again returns 409 FILE_ALREADY_ATTACHED with the receiptId in details, even after you delete the receipt. Upload the file again to attach it again.5
List, download and delete
- The list has no download links. Get one receipt to receive a
downloadUrl. - The link works without an API key for 1 hour, so never log, store or share it. Request a new one when you need the file again.
- The link has no file name. Save the file with the receipt’s
fileName. - JPEG and PNG receipts may be compressed after upload, so the downloaded image can be smaller than the one you uploaded.
- Deleting returns
204and sets the transaction’s review back to pending. - A link you got before the delete keeps working until it expires.
- Deleting the same receipt again returns
404 RECEIPT_NOT_FOUND.