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. Get a test API key
Section titled “1. Get a test API key”- Sign in at auth.rivecard.com with your email (or a passkey).
- Open Developers → API keys in the dashboard and create a test key. The secret is shown once — store it in your secrets manager.
export RIVE_KEY=rk_test_...2. Create an account holder and fund it
Section titled “2. Create an account holder and fund it”The account holder is the person or company that legally owns the card.
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}'3. Issue a card with controls
Section titled “3. Issue a card with controls”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}}'4. Simulate a purchase
Section titled “4. Simulate a purchase”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.
Conventions
Section titled “Conventions”- 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-Keyon 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-Idheader.