Skip to main content
Prerequisite: have a session token. See Authentication.

​
Card lifecycle

​
API flows (step‑by‑step)

1

List cards

Endpoint: GET /cards
2

Create a card

Endpoint: POST /cards
Body: optional encryptedName (encrypted card label) and optional limit with amountCents and frequency.
Tip: To set a card label, call POST /encryption/encrypt first and pass the returned value as encryptedName (see Encryption).
curl -s \
  -H 'Authorization: Bearer <SESSION_TOKEN>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <UUID>' \
  -d '{"limit": {"amountCents": 2500, "frequency": "perAuthorization"}}' \
  https://dev-api.machines.cash/partner/v1/cards
3

Update status or limits

Endpoint: PATCH /cards/
4

Delete a card

Endpoint: DELETE /cards/
5

Create a card secrets session (optional)

Endpoint: POST /cards/secrets/session
Body: send an empty JSON object if your client sets Content-Type: application/json.
curl -s \
  -H 'Authorization: Bearer <SESSION_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{}' \
  https://dev-api.machines.cash/partner/v1/cards/secrets/session
6

Get card secrets (optional)

Endpoint: POST /cards//secrets
Body: (from the secrets session helper)

​
Fields (create/update)

​
encryptedName
object
Optional encrypted card label field . Generate with POST /encryption/encrypt.
​
limit.amountCents
integer
Spending cap in cents.
​
limit.frequency
string
One of: perAuthorization, per24HourPeriod, per7DayPeriod, per30DayPeriod, perYearPeriod, allTime.

​
Response (secrets session)

​
sessionId
string
required
Session id used to fetch encrypted PAN/CVC.
​
secretKey
string
required
16‑byte secret (hex) used to decrypt PAN/CVC with AES‑128‑GCM.

​
Response (secrets)

​
encryptedPan.data
string
required
Base64 ciphertext + auth tag.
​
encryptedPan.iv
string
required
Base64 IV.
​
encryptedCvc.data
string
required
Base64 ciphertext + auth tag.
​
encryptedCvc.iv
string
required
Base64 IV.
​
expirationMonth
number
required
Expiration month (MM).
​
expirationYear
number
required
Expiration year (YYYY).
​
last4
string
required
Last 4 digits.

​
Card labels vs card secrets

  • Card labels use /encryption/encrypt and /encryption/decrypt.
  • Card secrets (PAN/CVC) use /cards/secrets/session + /cards//secrets.
  • Decrypt card labels on your backend and send plaintext labels to your frontend.
  • Card labels are optional, but recommended for clean UI.

​
Card limits

  • amountCents: integer amount in cents (e.g., 5000 = $50). Minimum 1.
  • frequency: one of
    • perAuthorization — max per single authorization
    • per24HourPeriod — rolling 24‑hour spend cap
    • per7DayPeriod — rolling 7‑day spend cap
    • per30DayPeriod — rolling 30‑day spend cap
    • perYearPeriod — rolling 1‑year cap
    • allTime — lifetime cap
Examples 
{ "limit": { "amountCents": 5000, "frequency": "perAuthorization" } }
{ "limit": { "amountCents": 20000, "frequency": "per24HourPeriod" } }
To change a limit, PATCH the card with a new limit object. To remove a limit, set a permissive value (for example a very high allTime cap) or contact us if you need a true “no limit” configuration for your program.

​
Lock / unlock / update limits

  • PATCH /cards/ with status: “locked” to pause spend.
  • Set status: “active” to unlock.
  • Update limits by sending a new limit payload.

​
Delete

DELETE /cards/ cancels immediately.

​
Card number secrets (PAN/CVC)

This flow is only for retrieving the card number (PAN) and CVC. Do not use it for card labels.
  1. Call POST /cards/secrets/session to get sessionId and secretKey.
  2. Call POST /cards//secrets with .
  3. Decrypt encryptedPan and encryptedCvc locally using AES‑128‑GCM with the secretKey.
This endpoint requires the cards.secrets.read scope.
/encryption/decrypt is for card labels only. Use /cards//secrets for PAN/CVC.
The sessionId used here is different from your API session token. Always request it from /cards/secrets/session.
No decrypted PAN/CVC ever leaves your process; only encrypted blobs are returned by the API.