Skip to content

docs: document receipt delivery confirmation endpoint #542

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
claude wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: document receipt delivery confirmation endpoint #542

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -357,6 +357,26 @@ In the manual cancellation flow, `OUTGOING_PAYMENT.COMPLETED` fires after the re
</Tab>
</Tabs>

## Receipt Delivery Confirmation

Some platforms are contractually required to send a receipt to their customer after a transaction completes. Use the receipt confirmation endpoint to record when the receipt was delivered:

```bash
POST /transactions/{transactionId}/confirm

{
"receiptDeliveryConfirmedAt": "2025-08-15T14:31:00Z"
}
```

**Response:** Returns the updated transaction with `receiptDeliveryConfirmedAt` populated.
Comment on lines +364 to +372
Copy link
Copy Markdown
Contributor

@greptile-apps greptile-apps Bot Jun 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 The code block embeds the JSON request body inside a bash block with a bare HTTP method line, which is not a runnable command. The Mintlify style guide (CLAUDE.md) requires complete, runnable examples that users can copy and execute. Splitting the request and response into proper blocks — or using a curl form — keeps this consistent with the guide's standard and makes it clear to the reader that the JSON is a request body, not bash syntax.

Suggested change
```bash
POST /transactions/{transactionId}/confirm
{
"receiptDeliveryConfirmedAt": "2025-08-15T14:31:00Z"
}
```
**Response:** Returns the updated transaction with `receiptDeliveryConfirmedAt` populated.
```bash
curl -X POST "https://api.example.com/transactions/{transactionId}/confirm" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{"receiptDeliveryConfirmedAt": "2025-08-15T14:31:00Z"}'

Response: Returns the updated transaction with receiptDeliveryConfirmedAt populated:

{
  "id": "Transaction:abc123",
  "status": "COMPLETED",
  "receiptDeliveryConfirmedAt": "2025-08-15T14:31:00Z"
}

**Context Used:** mintlify/CLAUDE.md ([source](https://app.greptile.com/lightspark/github/lightsparkdev/grid-api/-/custom-context?memory=8705e0ee-b98a-4325-9b4d-e1f5638b408a))

<details><summary>Prompt To Fix With AI</summary>

`````markdown
This is a comment left during a code review.
Path: mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx
Line: 364-372

Comment:
The code block embeds the JSON request body inside a `bash` block with a bare HTTP method line, which is not a runnable command. The Mintlify style guide (`CLAUDE.md`) requires complete, runnable examples that users can copy and execute. Splitting the request and response into proper blocks — or using a `curl` form — keeps this consistent with the guide's standard and makes it clear to the reader that the JSON is a request body, not bash syntax.

```suggestion
```bash
curl -X POST "https://api.example.com/transactions/{transactionId}/confirm" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"receiptDeliveryConfirmedAt": "2025-08-15T14:31:00Z"}'

Response: Returns the updated transaction with receiptDeliveryConfirmedAt populated:

{
  "id": "Transaction:abc123",
  "status": "COMPLETED",
  "receiptDeliveryConfirmedAt": "2025-08-15T14:31:00Z"
}

**Context Used:** mintlify/CLAUDE.md ([source](https://app.greptile.com/lightspark/github/lightsparkdev/grid-api/-/custom-context?memory=8705e0ee-b98a-4325-9b4d-e1f5638b408a))

How can I resolve this? If you propose a fix, please make it concise.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!


If you omit `receiptDeliveryConfirmedAt` from the request body, Grid uses the current server time. Calling this endpoint again updates the stored confirmation time.
Comment on lines +372 to +374
Copy link
Copy Markdown
Contributor

@greptile-apps greptile-apps Bot Jun 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Missing idempotency / error behavior documentation

The section documents the happy path and the "omit the field" shortcut, but skips documenting what happens when the call is made for a transaction that doesn't exist, is not yet COMPLETED, or belongs to a different customer. The AGENTS.md style guide calls for "troubleshooting for likely failure points" and documenting error HTTP status codes. A developer who receives a 404 or 422 on this endpoint will have nowhere to look in the guide.

Context Used: mintlify/AGENTS.md (source)

Prompt To Fix With AI 
This is a comment left during a code review.
Path: mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx
Line: 372-374

Comment:
**Missing idempotency / error behavior documentation**

The section documents the happy path and the "omit the field" shortcut, but skips documenting what happens when the call is made for a transaction that doesn't exist, is not yet `COMPLETED`, or belongs to a different customer. The `AGENTS.md` style guide calls for "troubleshooting for likely failure points" and documenting error HTTP status codes. A developer who receives a 404 or 422 on this endpoint will have nowhere to look in the guide.

**Context Used:** mintlify/AGENTS.md ([source](https://app.greptile.com/lightspark/github/lightsparkdev/grid-api/-/custom-context?memory=51934046-75fb-42d3-9870-f42d61cb60e3))

How can I resolve this? If you propose a fix, please make it concise.


<Info>
This endpoint is only necessary if your platform agreement requires receipt confirmation. Most integrations do not need this step.
</Info>

## Listing Transactions

Query all transactions for a customer or date range:
Expand Down
Loading