Errors & conventions

Response envelopes

Success

{ "success": true, "data": { "...": "..." } }

Error — non-2xx responses carry a machine-readable code and a message:

{ "success": false, "error": { "code": "APPLICATION_NOT_FOUND", "message": "..." } }

Common error codes

Code	HTTP	Meaning
INVALID_APPLICATION_SIGNATURE	401	The access-token request signature didn't verify.
SIGNATURE_EXPIRED	401	The signed timestamp is too old.
SIGNATURE_REUSED	401	The nonce was already used.
INVALID_JWT_TOKEN	401	Missing / expired / malformed bearer token.
APPLICATION_NOT_FOUND	404	Unknown application / partner.

Conventions

• Auth: a missing or expired token returns 401. Mint a new one (see Authentication).
• Idempotency: externalUserId dedupes users; paymentReference dedupes repayments.
• Amounts: always USD decimals.
• Timestamps: Unix seconds unless stated otherwise.

Quickstart checklist

1. ☐ Generate an Ed25519 key pair; send Yumi your publicKey + email. Receive your partner id + webhook secret.
2. ☐ Implement token minting (POST /auth-apps/access-token).
3. ☐ POST /card/add-user for your users; update-user as data changes.
4. ☐ Handle the CREDIT_LIMIT webhook (verify X-Signature); store the limit.
5. ☐ POST /card/authorize-credit to draw; keep creditId.
6. ☐ POST /card/submit-repayment on repayment.