> ## Documentation Index
> Fetch the complete documentation index at: https://direct-api.reap.global/llms.txt
> Use this file to discover all available pages before exploring further.

# Attach receipts to card transactions from your own system

> Upload a receipt file, attach it to a card transaction, and list, download or delete it, all from your own tools.

## 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

```mermaid theme={"system"}
sequenceDiagram
    participant You as Your backend
    participant API as Business Account API
    You->>API: POST /files (purpose=card_receipt)
    API-->>You: file id, status checking
    loop every 2 to 5 seconds
        You->>API: GET /files/{fileId}
    end
    API-->>You: status ready
    You->>API: POST /cards/activities/{activityId}/receipts
    API-->>You: receipt id
    You->>API: GET /cards/activities/{activityId}/receipts/{receiptId}
    API-->>You: downloadUrl (valid 1 hour)
```

| Step | What you do | Endpoint | Scope needed |
| - | - | - | - |
| 1 | Upload the file | `POST /files` | `card_activities:write` |
| 2 | Wait for the scan | `GET /files/{fileId}` | `card_activities:write` |
| 3 | Attach the file | `POST /cards/activities/{activityId}/receipts` | `card_activities:write` |
| 4 | List receipts | `GET /cards/activities/{activityId}/receipts` | `card_activities:read` |
| 5 | Download a receipt | `GET /cards/activities/{activityId}/receipts/{receiptId}` | `card_activities:read` |
| 6 | Delete a receipt | `DELETE /cards/activities/{activityId}/receipts/{receiptId}` | `card_activities:write` |

## Before you begin

* A team administrator has created an API key with `card_activities:read` and `card_activities:write`. See [Authentication](https://direct-api.reap.global/api-reference/authentication.md).
* You have the `id` of a card transaction from [List card activities](https://direct-api.reap.global/api-reference/cards/list-card-account-activities.md).

```bash theme={"system"}
export REAP_API="https://api.global.direct.reap.global/2026-07-13"
export REAP_KEY="your-api-key"   # load from a secrets manager in production
```

## Steps

**1. Upload the file**

Send a `multipart/form-data` request. Put `purpose=card_receipt` before the `file` field.

```bash theme={"system"}
curl -X POST "$REAP_API/files" \
  -H "x-api-key: $REAP_KEY" \
  -F "purpose=card_receipt" \
  -F "file=@invoice-INV-20431.pdf"
```

```json theme={"system"}
{
  "id": "8f14e45f-ceea-4e67-a1b2-0f3c9d7a1b11",
  "purpose": "card_receipt",
  "filename": null,
  "size": 48213,
  "contentType": "application/pdf",
  "status": "checking",
  "createdAt": "2026-10-29T01:00:00.000Z"
}
```

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**

```bash theme={"system"}
curl "$REAP_API/files/8f14e45f-ceea-4e67-a1b2-0f3c9d7a1b11" -H "x-api-key: $REAP_KEY"
```

* 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**

```bash theme={"system"}
curl -X POST "$REAP_API/cards/activities/txn_00000000-0000-0000-0000-00000000f001/receipts" \
  -H "x-api-key: $REAP_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: attach-txn_00000000-0000-0000-0000-00000000f001-8f14e45f" \
  -d '{ "fileId": "8f14e45f-ceea-4e67-a1b2-0f3c9d7a1b11" }'
```

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**

```bash theme={"system"}
curl "$REAP_API/cards/activities/$ACTIVITY_ID/receipts" -H "x-api-key: $REAP_KEY"
curl "$REAP_API/cards/activities/$ACTIVITY_ID/receipts/$RECEIPT_ID" -H "x-api-key: $REAP_KEY"
curl -X DELETE "$REAP_API/cards/activities/$ACTIVITY_ID/receipts/$RECEIPT_ID" -H "x-api-key: $REAP_KEY"
```

* 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

| Limit | Value |
| - | - |
| File size | 10 MB |
| File types | PDF, JPEG, PNG, GIF, HEIC |
| Receipts per transaction | 3 (`422 RECEIPT_LIMIT_REACHED` after that) |
| Time to attach after upload | 24 hours |
| Transaction on a terminated card | `422 ACTIVITY_CARD_TERMINATED` |

## Related

* [Activities](https://direct-api.reap.global/concepts/activities.md)
* [Upload a file](https://direct-api.reap.global/api-reference/files/upload-a-file.md)
* [Attach a receipt to a card account activity](https://direct-api.reap.global/api-reference/cards/attach-a-receipt-to-a-card-account-activity.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.