# Cards & EUR Account

> Coming soon, upon request — this feature is turned on for your tenant by the Aurea team. [Contact us](https://www.aureahub.com/contact)

Give your users a payment card and a personal euro account (an IBAN) on top of their wallet: they sign in to the card program with their wallet, complete onboarding once, and then spend by card, receive euros by bank transfer and pay out to any bank account.

## Overview

- **A card program, reached through Aurea.** The routes under `/v1/gnosis` carry your app's calls to the card program your tenant is set up with, and answer what it answered. The path, the fields and the codes keep the names the API gives them.
- **The user's wallet signs.** The user signs in to the card program with one of their EVM wallets (a Sign-In with Ethereum message), and that wallet's key signs every later consent. A wallet whose key the platform holds for your tenant can sign through [Sign Personal Message](https://docs.aureahub.com/docs/dapps-sign.md).
- **A smart account holds the money.** Onboarding creates the user's smart account on Gnosis Chain. The card spends from it, and the user's EUR account delivers incoming bank transfers into it as the EURe token.
- **The EUR account.** Once onboarding is done, the user gets an IBAN: euros sent to it arrive as EURe in the smart account, and a payout sends EURe from it as euros to a bank account.

## Coming soon, upon request

[Coming soon, upon request](https://docs.aureahub.com/docs/feature-availability.md) Cards and the EUR account are set up per tenant. Your app can tell: [Available Features](https://docs.aureahub.com/docs/tenant-features.md) answers `eurAccountIban` `true`, and [Get Your Tenant](https://docs.aureahub.com/docs/tenant-info.md) answers `configuration.bankingProvider` `"gnosis"`. Until then:

- every card route answers `403` (`ForbiddenError`) — [Local Status](https://docs.aureahub.com/docs/cards-local-status.md) included, [End the Session](https://docs.aureahub.com/docs/cards-session-clear.md) excepted;
- a route that reaches the card program before your tenant's card program access is set up answers `400`;
- payouts and the EUR account's authorization link answer `503` or `422` until your tenant's EUR account access is set up ([Pay Out to a Bank](https://docs.aureahub.com/docs/cards-payout.md), [Authorization Link](https://docs.aureahub.com/docs/cards-iban-authorize.md));
- showing a card's number answers `503` `CARD_REVEAL_NOT_CONFIGURED` until card reveal is set up ([Card Reveal Token](https://docs.aureahub.com/docs/cards-reveal-token.md)).

## Calling the Card Routes

- Every card route takes the signed-in user's access token (`Authorization: Bearer …`, [Authentication](https://docs.aureahub.com/docs/authentication.md)) and acts for that user. No tenant signature is asked: your app calls them.
- They are for the roles that sign: `user`, `owner`, `tenantadmin` and `signer` ([Roles](https://docs.aureahub.com/docs/authentication.md)). Any other role answers `403`.
- Amounts of the EUR account are decimal euro strings such as `"10.00"`, not smallest units.

## The Order of Calls

1. **Check where the user is:** [Local Status](https://docs.aureahub.com/docs/cards-local-status.md) answers from Aurea's records alone, without reaching the card program: whether a session is open, the onboarding `status`, the smart account and whether the EUR account is linked. Call it whenever your app opens.
2. **Sign in to the card program:** [Sign-In Message](https://docs.aureahub.com/docs/cards-auth-message.md), then [Sign In](https://docs.aureahub.com/docs/cards-auth-challenge.md) with the signed message. A new user then [signs up](https://docs.aureahub.com/docs/cards-auth-signup.md).
3. **Onboarding**, in this order (each step below): terms, identity check, source of funds, phone, smart account.
4. **The EUR account:** activate it, and link the user's address to it for payouts.
5. **Cards:** accept the card terms, create a virtual card, show it, freeze or void it, list its transactions.
6. **Payouts:** [Payout Message](https://docs.aureahub.com/docs/cards-payout-message.md), signed by the user, then [Pay Out to a Bank](https://docs.aureahub.com/docs/cards-payout.md).

## The Card Program Session

Most routes act inside the user's session with the card program. Aurea keeps that session for the user, encrypted, and never hands it to you except to reveal a card.

1. [Sign-In Message](https://docs.aureahub.com/docs/cards-auth-message.md) with the wallet's `address` answers the sign-in message (Sign-In with Ethereum, EIP-4361), ready to sign: the address in lower case, a fresh nonce, the time, and the card program's fixed texts. Use `message` exactly as answered — never rebuild or reformat it.
2. Sign `message` (its UTF-8 bytes) with `personal_sign` (EIP-191) by the wallet whose address it names. **A wallet whose key the platform holds for your tenant** (custodial): sign through [Sign Personal Message](https://docs.aureahub.com/docs/dapps-sign.md) — `message`: the answer's `messageHex`; `walletAddress`: the address. It answers the `signature`. For a client-side or MPC wallet it answers what to sign on the device instead.

- **Why the address is in lower case:** the card program looks addresses up exactly as written, and keeps them in lower case. The message always names it so; send the same lower-case `address` to Sign In.
- Sign and send it within a few minutes: the nonce is for one sign-in.

1. [Sign In](https://docs.aureahub.com/docs/cards-auth-challenge.md) with `message`, `signature` and `address`. Aurea stores the session the card program answers, valid until its expiry or 24 hours. `isExistingGnosisUser` says whether the wallet already has an account there: `true`, and the session is ready (`userData` holds the account); `false`, and the user signs up next.
2. [Sign Up](https://docs.aureahub.com/docs/cards-auth-signup.md) registers the user with the email of their Aurea profile and replaces the session with the full one.

- **An expired session** answers `403` with `details.code` `CARD_PROGRAM_SESSION_EXPIRED` — never `401`, so your app's own sign-out is not triggered. Sign in again (steps 1–3); the onboarding the user completed is kept.
- [End the Session](https://docs.aureahub.com/docs/cards-session-clear.md) forgets the session at once, for example when the user signs out.

## Onboarding

1. **Terms:** [Terms](https://docs.aureahub.com/docs/cards-terms-get.md) lists them with whether each is accepted; accept `general-tos` and `privacy-policy` with [Accept Terms](https://docs.aureahub.com/docs/cards-terms-accept.md).
2. **Identity check:** [Identity Check](https://docs.aureahub.com/docs/cards-kyc.md) answers the `url` of the identity check; open it in a browser view and let the user complete it.
3. **Source of funds:** [Source of Funds Questions](https://docs.aureahub.com/docs/cards-sof-get.md), then [Answer Source of Funds](https://docs.aureahub.com/docs/cards-sof-submit.md) with one answer per question.
4. **Phone:** [Send a Phone Code](https://docs.aureahub.com/docs/cards-phone-start.md) with the number, then [Check the Phone Code](https://docs.aureahub.com/docs/cards-phone-check.md) with the code the user received.
5. **Smart account:** [Smart Account](https://docs.aureahub.com/docs/cards-account-config.md) answers it once it exists; otherwise [Create the Smart Account](https://docs.aureahub.com/docs/cards-account-deploy.md). Aurea keeps its `address` for the user (`gnosisAddress` in Local Status).

[Get the Account](https://docs.aureahub.com/docs/cards-user.md) answers the user's account at the card program — `kycStatus` (`notStarted`, `pending`, `processing`, `resubmissionRequested`, `requiresAction`, `rejected` or `approved`), `isSourceOfFundsAnswered`, `isPhoneValidated`, `safeWallets` and `bankingDetails` — so your app shows the next step. Each step Aurea sees completed moves `status` in Local Status forward: `pending`, `terms_accepted`, `source_of_funds_completed`, `mobile_verified`, `active`; it never moves back.

## The EUR Account

The user's EUR account is activated in one of two ways; then the address that signs payouts is linked to it.

### Activate with a signature

1. [IBAN Signing Message](https://docs.aureahub.com/docs/cards-iban-message.md) answers the message to sign (`data.message`).
2. The user's wallet signs it with `personal_sign`, and [Activate the EUR Account](https://docs.aureahub.com/docs/cards-iban-activate.md) sends `{ "signature" }` inside the card program session. Aurea also links the signing address for payouts with the same signature.

### Activate through the issuer's consent page

Used when the user's address already belongs to an EUR account of theirs, so payouts must run with the user's own consent:

1. **Sign the link message** (`I hereby declare that I am the address owner.`, [Link Message](https://docs.aureahub.com/docs/cards-link-message.md)) with the wallet that signed in to the card program.
2. **Phase 1:** [Authorization Link](https://docs.aureahub.com/docs/cards-iban-authorize.md) with that `signature` and your app's `redirectScheme`. It answers `authUrl`, `redirectUri`, `codeVerifier`, a `siweMessage` to sign and — when the smart account exists — `safeMessageHash`, `delayModuleAddress` and `linkMessageQueueCalldata`.
3. **Queue the smart account's consent** (when `delayModuleAddress` is answered): send a transaction from the wallet to `delayModuleAddress` with `data` `linkMessageQueueCalldata` and value 0 on Gnosis Chain ([Get Nonce](https://docs.aureahub.com/docs/dapps-nonce.md), sign, [Broadcast Transaction](https://docs.aureahub.com/docs/dapps-broadcast.md)), and keep its hash. Aurea completes it once the module's 180-second delay has passed.
4. **Sign** `siweMessage` with `personal_sign`, and the 32 bytes of `safeMessageHash` with `personal_sign`.
5. **Phase 2:** [Authorization Link](https://docs.aureahub.com/docs/cards-iban-authorize.md) again with `siweSignature`, `safeLinkSignature` and `linkMessageTxHash`. It answers the `authUrl` to open.
6. **Open `authUrl`** in a browser view. When the user has consented, the browser is sent to `<redirectScheme>://eur-account-callback?code=…&state=…`, or `…?error=…` when they did not.
7. **Finish:** [Activate the EUR Account](https://docs.aureahub.com/docs/cards-iban-activate.md) with `{ "consentId": <code>, "codeVerifier" }`. Aurea keeps the user's consent for payouts, links the smart account and moves the IBAN to it.

Each signature in phases 1 and 2 is optional: without one, the consent page asks the user to sign in there instead.

### Link the address for payouts

A payout is accepted only from an address linked to the EUR account. Activation with a signature links it; to link it later, sign the [Link Message](https://docs.aureahub.com/docs/cards-link-message.md) and send it to [Link the Address](https://docs.aureahub.com/docs/cards-link-address.md).

The IBAN and BIC: `bankingDetails.eurAccountIban` and `bankingDetails.eurAccountBic` of [Get the Account](https://docs.aureahub.com/docs/cards-user.md); `bankingDetails.eurAccountIbanStatus` says whether it is assigned.

## Paying Out to a Bank

1. [Payout Message](https://docs.aureahub.com/docs/cards-payout-message.md) with the `amount` in euros and, optionally, the `destinationIban`: it answers the exact `message` — `Send EUR <amount> to <IBAN> at <time>` — and the `resolvedIban`. Without `destinationIban`, it is the IBAN of the user's own EUR account.
2. The user's wallet signs `message` with `personal_sign`, unchanged.
3. [Pay Out to a Bank](https://docs.aureahub.com/docs/cards-payout.md) with the same `amount`, `destinationIban`, `message` and `signature`: `201` with the order's `orderId` and `status`. EURe leaves the smart account and euros are sent by SEPA transfer.

## Cards

1. **Card terms first:** accept `card-issuer-tos` with [Accept Terms](https://docs.aureahub.com/docs/cards-terms-accept.md); without it, creating a card answers `403` `CARD_TERMS_REQUIRED`.
2. [Create a Virtual Card](https://docs.aureahub.com/docs/cards-virtual-create.md): `201` with the card, activated when it was created inactive.
3. [List Cards](https://docs.aureahub.com/docs/cards-list.md): each card's `id`, `lastFour`, `isVirtual`, `statusCode` (`1000` active, `1001` not activated, `1005` frozen), `statusName`, `isFrozen` and `activatedAt`.
4. **Show the card's details** in the card program's secure display component, inside your app: [Card Reveal Token](https://docs.aureahub.com/docs/cards-reveal-token.md) answers the token it takes. The details never pass through your servers or Aurea's. Aurea gives the component's integration package to your team when Cards is turned on for your tenant [Coming soon, upon request](https://docs.aureahub.com/docs/feature-availability.md).
5. [Freeze](https://docs.aureahub.com/docs/cards-freeze.md) and [Unfreeze](https://docs.aureahub.com/docs/cards-unfreeze.md) a card; [Activate](https://docs.aureahub.com/docs/cards-activate.md) one that is not active; [Void](https://docs.aureahub.com/docs/cards-void.md) it for good.
6. [Card Transactions](https://docs.aureahub.com/docs/cards-transactions.md), filtered by dates, currency, merchant category or type.

## Answers Passed Through

Except where a page lists the fields Aurea writes — the cards, the payout, the authorization link, Local Status — a route answers the card program's answer, passed through unchanged. Those pages' examples are **illustrative**: they show only the fields Aurea or its own app reads, the answer may carry fields not listed, and a field may be absent. Build so that an unknown field is ignored.

## Errors

The usual envelope ([Errors & Codes](https://docs.aureahub.com/docs/errors.md)). What the card program refuses comes back with its message:

| Status | When |
| --- | --- |
| 400 | The card program refused the request or does not know the resource, or your tenant's card program access is not set up. |
| 403 | Cards are not on for your tenant; the role does not sign; the session is missing or expired (`details.code` `CARD_PROGRAM_SESSION_EXPIRED`); the card program refused it; the card terms are not accepted (`CARD_TERMS_REQUIRED`). |
| 409 | The card program already has it — for example a sign-up of an account that exists. Sign Up answers `200` instead, with `alreadyRegistered`. |
| 422 | The card program refused the content; or a step of the EUR account or of a payout is missing (each page says which). |
| 423 | A freeze stops the user, the wallet or your tenant from signing ([Freezes & Quarantines](https://docs.aureahub.com/docs/guide-freezes.md)): the authorization link, the payout message and the payout. |
| 503 | The card program is unreachable, took more than 10 seconds, rate-limited the call or failed; or the EUR account access, or card reveal (`CARD_REVEAL_NOT_CONFIGURED`), is not set up. |

---

Web version: https://docs.aureahub.com/#guide-cards