# Packflip Partner API

> Sell real, graded collectible card packs inside your product through one REST API. Partners prepay a USD balance in USDC on Base; Packflip holds the cards, buys them back, ships them, or mints them as NFTs to users' wallets.

- Production: https://partner.packflip.xyz (Base, real money)
- Sandbox: https://sandbox.partner.packflip.xyz (Base Sepolia, test credit, synthetic catalog)
- Authenticate with `Authorization: Bearer pk_...` from server code only.
- `POST /api/v2/operations` requires an `Idempotency-Key` header.
- Money is a decimal string such as "1.500000", never a float.
- On 409, branch on `error.code`: insufficient_balance, out_of_stock, conflict, or idempotency_conflict.

## Most common integration flow

1. `POST /api/v2/customers` with `externalUserId`; on 409 `conflict`, `GET /api/v2/customers/by-external-id/{externalUserId}`. Store the `cus_` ID.
2. `GET /api/v2/vending-machines`.
3. Save a purchase record, then `POST /api/v2/operations` with `{"kind":"order","mode":"offchain","customerId","vendingMachineId","quantity":1,"reveal":"sealed"}` and `Idempotency-Key` derived from that record. Reuse the key on every retry.
4. `POST /api/v2/customers/{customerId}/cards/reveal` with `{"cardIds":[...]}` when the user opens the pack.
5. `GET /api/v2/customers/{customerId}/cards`. A card can be bought back or redeemed only when `status == "active"`, `sealed == false`, and `onchain == null`.
6. `POST /api/v2/operations` with `{"kind":"buyback","mode":"offchain",...}` or `{"kind":"redemption","mode":"offchain","shipmentInfo":{"country","name","phone","address1","city","postalCode",...}}`, each with its own stored key. `shipmentInfo.country` is a value from `GET /api/v2/shipping-countries`, sent verbatim.
7. Re-fetch the operation (`GET /api/v2/operations/{operationId}`) and the cards.

Full walkthrough with retry handling: https://sandbox.partner.packflip.xyz/docs/lifecycle.md

## Guides

- [Sandbox quickstart](https://sandbox.partner.packflip.xyz/docs/quickstart.md): From a new organization to a drawn card in ten minutes.
- [Off-chain lifecycle](https://sandbox.partner.packflip.xyz/docs/lifecycle.md): The whole purchase flow with retries: customer, draw, reveal, buyback or redemption.
- [Core concepts](https://sandbox.partner.packflip.xyz/docs/concepts.md): Environments, balance, customers, cards, and operations.
- [Funding your balance](https://sandbox.partner.packflip.xyz/docs/funding.md): USDC deposits on Base, and test credit in the sandbox.
- [Cards and operations](https://sandbox.partner.packflip.xyz/docs/cards.md): Draws, sealed packs, refunds, buybacks, and redemption.
- [On-chain cards](https://sandbox.partner.packflip.xyz/docs/onchain.md): Mint cards to a wallet on Base and buy minted cards back.
- [Webhooks](https://sandbox.partner.packflip.xyz/docs/webhooks.md): Event types, payloads, signatures, and retries.
- [Errors, idempotency, and retries](https://sandbox.partner.packflip.xyz/docs/errors.md): Error codes, safe retries, lists, and versioning.
- [Going live](https://sandbox.partner.packflip.xyz/docs/going-live.md): What changes when you move from the sandbox to production.
- [Building with a coding agent](https://sandbox.partner.packflip.xyz/docs/agents.md): llms.txt, a starter prompt, and integration rules.

## Reference

- [OpenAPI 3.1 document](https://sandbox.partner.packflip.xyz/openapi.json): the source of truth for every request and response
- [All guides in one file](https://sandbox.partner.packflip.xyz/llms-full.txt)

## Optional

- [Partner Terms of Service](https://sandbox.partner.packflip.xyz/terms)
- [Partner Privacy Policy](https://sandbox.partner.packflip.xyz/privacy)