Skip to main content

What you’ll build

By the end of this guide, your system will be able to:
  1. Upload a receipt file and wait for its malware scan.
  2. Attach it to a card transaction.
  3. 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:read and card_activities:write. See Authentication.
  • You have the id of a card transaction from List card activities.

Steps

1

Upload the file

Send a multipart/form-data request. Put purpose=card_receipt before the file field.
We check the file type from its content, not its name. A file that isn’t a PDF, JPEG, PNG, GIF or HEIC returns 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 status is ready. This can take up to 5 minutes.
  • blocked or failed means the file can’t be used. Upload a different one.
3

Attach it to the transaction

Attach within 24 hours of the upload. The answer is 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 204 and 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.

Limits