AI Integration Prompts

Use these copy-paste prompts with your AI coding assistant when you want help integrating the CoinsSend API into a full checkout flow. Each prompt tells the assistant to follow the canonical docs, keep merchant secrets server-side, and verify the work inside your own project.

Before you ask an AI assistant

Read these source-of-truth docs first, then paste the relevant prompt into your coding assistant:

• Getting Started
• OpenAPI 3.1
• Signature Test Vectors
• API Quickstart
• Authentication
• Invoices
• Webhooks
• Error Handling
• Rate Limits

Full checkout integration prompt

You are helping me add a CoinsSend full checkout integration to my application.

Use the canonical CoinsSend docs as the source of truth:
- getting-started.md
- QUICKSTART.md
- authentication.md
- invoices.md
- webhooks.md
- error-handling.md
- rate-limits.md
- openapi.json
- signature-test-vectors.json

Implement a server-side checkout flow using these values only after I replace them:
- Base API URL: {BASE_URL}
- Merchant ID: {MERCHANT_ID}
- API key environment variable name: {API_KEY_ENV}
- Order ID: {ORDER_ID}
- Amount: {AMOUNT}
- Success redirect URL: {SUCCESS_URL}
- Cancel redirect URL: {CANCEL_URL}
- Webhook URL: {WEBHOOK_URL}

Requirements:
1. Keep the merchant API key in environment variables or server secrets only. Never put it in frontend code, public code, logs, build output, or browser storage.
2. Create the invoice from server-side code. The frontend may ask my server to start checkout, but it must not sign merchant API requests.
3. Generate the PHP-compatible canonical JSON body from authentication.md, sign exactly md5(base64(canonical_body) + API_KEY), and send that same canonical string as the HTTP body. Verify the implementation against signature-test-vectors.json.
4. Send the required merchant authentication headers from the server request.
5. Include the order ID, amount, success URL, and cancel URL according to the invoice docs. Configure the merchant webhook callback in merchant settings; webhook_url is not an invoice-creation field.
6. Return or redirect the buyer to the invoice payment URL from the invoice creation response.
7. Treat success and cancel redirect URLs as UX signals only. Do not mark the order paid from a redirect. Payment confirmation must come from verified webhooks and persisted invoice status.
8. Persist the local order, CoinsSend invoice ID or code, payment URL, current status, and timestamps needed for reconciliation.
9. Handle invoice.paid as terminal success. Handle invoice.expired and aml.rejected.invoice as terminal failure states. Handle partial as not complete and keep the order awaiting full payment unless my business rules say otherwise.
10. Add a local uniqueness guard for repeated checkout starts. The API returns 409 for a duplicate order_id but does not replay the original response. Separately make webhook processing idempotent.
11. Add user-project tests and checks for signing, invoice creation, redirect URL behavior, status persistence, partial payment handling, expired handling, AML rejection handling, and the rule that frontend code never sees merchant secrets.
12. Run the relevant lint, type, unit, integration, and build checks available in my project, then report the exact commands and results.

Do not duplicate whole endpoint references in my code comments or docs. Link back to the canonical CoinsSend docs instead.

Webhook receiver prompt

Use this webhook assistant prompt whenever you need a webhook implementation checklist before code.

You are helping me implement a CoinsSend webhook receiver.

Use the canonical CoinsSend webhooks and authentication docs as the source of truth. Build the receiver in my existing server framework and match my project's routing, persistence, logging, and test patterns.

Requirements:
1. Preserve the raw request body before JSON parsing.
2. Read the X-Signature header from the request.
3. Verify the webhook with HMAC-SHA256 using the raw request body and the merchant API key from server secrets.
4. Use a constant-time comparison for signatures.
5. Reject missing or invalid signatures before parsing or trusting the payload.
6. Parse JSON only after signature verification passes.
7. Handle invoice.paid, invoice.expired, and aml.rejected.invoice events.
8. Persist terminal status changes in my database. invoice.paid is terminal success. invoice.expired and aml.rejected.invoice are terminal failure states.
9. Treat partial as not fully paid. Persist the partial state or payment progress without releasing goods or marking the order paid.
10. Make webhook handling idempotent so duplicate deliveries don't double-apply business effects. Use X-Idempotency-Key when present; it is currently guaranteed only for withdrawal events, so use an event/entity deduplication key otherwise.
11. Return a 2xx response only after the event is accepted for processing. Return a clear non-2xx response for invalid signatures or malformed payloads.
12. Add user-project tests and checks for raw body preservation, X-Signature verification, invalid signature rejection, duplicate delivery handling, invoice.paid, invoice.expired, aml.rejected.invoice, partial, and expired status persistence.
13. Run the relevant lint, type, unit, integration, and build checks available in my project, then report the exact commands and results.

Do not verify after parsing JSON. The raw request body must be captured and verified first.

Production hardening review prompt

You are reviewing my CoinsSend checkout integration for production readiness.

Use the canonical CoinsSend getting started, quickstart, authentication, invoices, webhooks, error handling, and rate limit docs as the source of truth. Inspect my existing implementation, tests, configuration, and runtime assumptions.

Review checklist:
1. Confirm merchant API keys are stored only in environment variables or server secrets and never exposed to frontend code, logs, build output, public repositories, or browser storage.
2. Confirm invoice creation happens server-side and merchant API requests are signed only on the server.
3. Confirm request signing generates the PHP-compatible canonical JSON body, signs md5(base64(canonical_body) + API_KEY) for legacy endpoints or timestamped HMAC-SHA256 for withdrawals, sends the same canonical body, and passes signature-test-vectors.json.
4. Confirm success and cancel redirect URLs are treated only as UX signals, never as payment confirmation.
5. Confirm verified webhooks or persisted status checks are the only source of payment confirmation.
6. Confirm webhook verification reads X-Signature, uses HMAC-SHA256, and verifies the raw request body before JSON parsing.
7. Confirm terminal state persistence covers invoice.paid as success and invoice.expired plus aml.rejected.invoice as failure states.
8. Confirm partial and expired statuses don't release goods or mark orders paid.
9. Confirm duplicate webhook deliveries are idempotent and repeated checkout starts use a local uniqueness guard without assuming the CoinsSend API replays a duplicate invoice response.
10. Confirm failures are handled clearly, including authentication and endpoint error shapes, invalid signatures, validation errors, rate limits, unknown write outcomes, expired invoices, partial payments, and AML rejection.
11. Confirm observability doesn't leak merchant secrets or signed payload material.
12. Confirm my user-project tests and checks cover signing, invoice creation, redirect behavior, webhook verification, terminal persistence, failure states, partial, expired, and secret handling.
13. Run the relevant lint, type, unit, integration, and build checks available in my project, then report the exact commands and results.

Do not add new SDK-specific setup instructions or copy full endpoint reference sections. If docs are needed, link back to the canonical CoinsSend docs.

Required guardrails

• Merchant API keys stay in environment variables or server secrets only.
• Frontend code must never sign merchant API requests or store merchant API keys.
• Invoice creation for checkout must happen on the server.
• Invoice and static-wallet request signing must use exactly md5(base64(canonical_body) + API_KEY).
• Withdrawal request signing must send Timestamp and use exactly hmac_sha256(base64(canonical_body) + "." + Timestamp, API_KEY).
• Generate one PHP-compatible canonical request body, sign it, send that same string, and pass the published signature vectors.
• Webhook verification is a separate contract: verify the exact raw received body bytes before JSON parsing.
• Webhook receivers must read X-Signature, verify with HMAC-SHA256, and preserve the raw request body before JSON parsing.
• Redirect success and cancel URLs are UX signals only, not payment confirmation.
• Payment confirmation must come from verified webhooks and terminal status persistence.
• Handle invoice.paid, invoice.expired, aml.rejected.invoice, partial, and expired explicitly.
• Persist terminal outcomes so invoice.paid closes the order as paid, while invoice.expired and aml.rejected.invoice close it as failed or rejected.
• Treat partial as not fully paid unless a separate business rule is intentionally implemented.
• Add user-project tests and checks for signing, webhook verification, redirects, persistence, failure states, duplicate deliveries, and secret handling.
• Link back to the canonical docs pages instead of duplicating endpoint references.

What not to ask the assistant to do

• Don’t ask it to put merchant API keys in frontend code, mobile clients, public repositories, logs, browser storage, or build output.
• Don’t ask it to sign CoinsSend merchant requests in the browser.
• Don’t ask it to mark an order paid after a success redirect.
• Don’t ask it to trust a cancel redirect as the final invoice state.
• Don’t ask it to verify webhooks after parsing JSON. Preserve and verify the raw request body first.
• Don’t ask it to skip X-Signature validation or replace HMAC-SHA256 with another webhook signing method.
• Don’t ask it to ignore partial, expired, invoice.expired, or aml.rejected.invoice states.
• Don’t ask it to blindly retry a withdrawal, static-wallet creation, or another write after an unknown outcome.
• Don’t ask it to invent a universal Idempotency-Key, global rate limit, symbolic wire error code, or static asset enum.
• Don’t ask it to hardcode credentials, merchant IDs, signatures, or production-looking secrets.
• Don’t ask it to duplicate whole endpoint reference sections when a link to the canonical docs is enough.