PackflipPartner
Get API keys

Sandbox quickstart

From a new organization to a drawn card in ten minutes.

Go from an empty organization to a drawn card in about ten minutes. Everything here runs in the sandbox, so no real money or cards are involved.

1. Create an organization and a key

  1. Sign in at sandbox.partner.packflip.xyz. The sandbox and production share one login, but their data is separate.
  2. Create or select an organization. API keys, balance, and customers belong to the organization, not to you.
  3. Open API keys, create a key, and copy it. It starts with pk_ and is shown only once.
export PACKFLIP_BASE_URL=https://sandbox.partner.packflip.xyz
export PACKFLIP_API_KEY=pk_...

Keep the key on your server. Every request sends it as a bearer token.

2. Add test credit

Operations draw from a prepaid USD balance. In the sandbox you can add test credit instead of sending testnet USDC, either with Add $100 test credit in the console or through the API:

curl -X POST "$PACKFLIP_BASE_URL/api/v2/sandbox/credits" \
  -H "Authorization: Bearer $PACKFLIP_API_KEY"

{
  "ledgerEntryId": "…",
  "creditedUsd": "100.000000",
  "balance": { "currency": "USD", "cash": "100.000000", "bonus": "0.000000", "total": "100.000000" }
}

Test credit can be added once an hour, up to a $1,000 balance. The endpoint returns 404 in production.

3. Pick a vending machine

A vending machine is a pack you can sell. Note its id and priceUsd.

curl "$PACKFLIP_BASE_URL/api/v2/vending-machines" \
  -H "Authorization: Bearer $PACKFLIP_API_KEY"

4. Create a customer

A customer represents one of your users and owns the cards they draw. Set externalUserId to your own user ID so you can look the customer up later.

curl -X POST "$PACKFLIP_BASE_URL/api/v2/customers" \
  -H "Authorization: Bearer $PACKFLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "externalUserId": "user_123" }'

The response contains the customer ID, for example cus_….

5. Draw a pack

Orders are commerce writes, so they need an Idempotency-Key. Generate a new one for each purchase and reuse it only when retrying that same purchase.

curl -X POST "$PACKFLIP_BASE_URL/api/v2/operations" \
  -H "Authorization: Bearer $PACKFLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-user_123-0001" \
  -d '{
    "kind": "order",
    "customerId": "cus_…",
    "vendingMachineId": 1,
    "quantity": 1
  }'

The response is an operation with status: "completed", the amount charged in chargedUsd, and the drawn cards in cards. Send the same request again and you get the same operation with replayed: true, and no second charge.

6. Show the cards

curl "$PACKFLIP_BASE_URL/api/v2/customers/cus_…/cards" \
  -H "Authorization: Bearer $PACKFLIP_API_KEY"

Each card has a name, an image URL with an imageSrcset for responsive images, and buybackUsd, its current buyback value.

7. Buy a card back

If your user does not want a card, buy it back. The value is credited to your balance.

curl -X POST "$PACKFLIP_BASE_URL/api/v2/operations" \
  -H "Authorization: Bearer $PACKFLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: buyback-user_123-0001" \
  -d '{
    "kind": "buyback",
    "mode": "offchain",
    "customerId": "cus_…",
    "cardIds": ["card_…"]
  }'

Next steps