Skip to content

Getting started

Rive Card has one API at https://api.rivecard.com. Your credential decides the environment: test credentials (rk_test_…) talk to the simulator, live credentials (rk_live_…) to a real card issuer. Live mode is switched on per organization once an issuer program is in place.

  1. Sign in at auth.rivecard.com with your email (or a passkey).
  2. Open Developers → API keys in the dashboard and create a test key. The secret is shown once — store it in your secrets manager.
Terminal window
export RIVE_KEY=rk_test_...

The account holder is the person or company that legally owns the card.

Terminal window
curl https://api.rivecard.com/v1/account_holders \
-H "Authorization: Bearer $RIVE_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"display_name":"Ada Lovelace","email":"ada@example.com"}'
curl https://api.rivecard.com/v1/account_holders/ah_.../fund \
-H "Authorization: Bearer $RIVE_KEY" -H "Content-Type: application/json" \
-d '{"amount":5000}'
Terminal window
curl https://api.rivecard.com/v1/cards \
-H "Authorization: Bearer $RIVE_KEY" -H "Content-Type: application/json" \
-d '{"account_holder_id":"ah_...","type":"multi_use",
"controls":{"spend_limits":[{"amount":2000,"interval":"per_transaction"},{"amount":5000,"interval":"monthly"}],
"allowed_mccs":["5734"],"max_transactions":10}}'
Terminal window
curl https://api.rivecard.com/v1/simulate/authorizations \
-H "Authorization: Bearer $RIVE_KEY" -H "Content-Type: application/json" \
-d '{"card_id":"card_...","amount":1500,"merchant":{"name":"OpenAI","mcc":"5734"}}'

The response is a transaction — approved, or declined with a decline_reason such as spend_limit_exceeded. Controls are checked before approval, not after the fact.

  • Ids are type-prefixed and time-sortable: card_…, ah_…, txn_…, evt_….
  • Pagination: ?limit=1-100&cursor=… → { object: "list", data, has_more, next_cursor }.
  • Idempotency: send Idempotency-Key on any POST; retries within 24 h replay the first response.
  • Errors: always { "error": { "type", "code", "message", "param?", "request_id" } } — see Errors.
  • Every response carries a Request-Id header.