--- title: Onramp intent description: Move BRL into BRS tokens minted to a whitelisted wallet on Solana, Ethereum, Base or Polygon. Your backend creates the intent, Nora returns PIX deposit info, your user pays by PIX, and the tokens land. --- An **onramp intent** is a single BRL → BRS mint. Your backend posts the amount, the destination wallet, and the chain; Nora returns PIX deposit info you surface to your user. Once the PIX lands, Nora mints BRS to the wallet and the intent reaches `completed`. ## Flow ```mermaid sequenceDiagram actor User participant App as Your app participant Nora as Nora API participant PIX as PIX rail User->>App: enters amount + destination wallet App->>Nora: POST /v2/intents/onramp
header: idempotency-key
body: { amountCents, destinationWallet, chainId, clientReference? } Nora-->>App: Intent
status: awaiting_fiat_payment
pixPayment: { ... } App-->>User: show PIX QR / complete copy-and-paste BR Code User->>PIX: pay PIX PIX->>Nora: payment confirmation loop until terminal App->>Nora: GET /v2/intents/:id Nora-->>App: intent (status advances) end Nora-->>App: status: completed ``` ## Create the intent `POST /v2/intents/onramp` `chainId` accepts `"solana"`, `"ethereum"`, or `"base"`. Base is live in both environments (sandbox = Base Sepolia, production = Base mainnet). It also accepts `"polygon"`, live in both environments (sandbox = Polygon Amoy, production = Polygon mainnet). | Field | Type | Required | Notes | |---|---|---|---| | `amountCents` | integer | Yes | BRL amount in **cents**, not decimals. `100.00 BRL → 10000`. Must be at least 500 (R$5.00 = 5 BRS minimum). | | `destinationWallet` | string | Yes | Wallet that receives the minted BRS: a Solana address, or an Ethereum address (`0x…`) registered through the [Wallets API](/integrate/api-reference/wallets). 1–255 chars. | | `chainId` | string | Yes | `"solana"`, `"ethereum"`, `"base"`, or `"polygon"`. The intent is minted on that chain; `destinationWallet` must be a whitelisted wallet on it. | | `clientReference` | string | No | Your own correlation ID, up to 255 chars. Echoed on the intent. Unique per environment, forever, across onramp and offramp; when omitted, the `idempotency-key` is stored and echoed as the reference. | Headers: | Header | Value | |---|---| | `X-API-Key` | Your API key. See [Authentication](/integrate/core-concepts/authentication). | | `idempotency-key` | Recommended. A UUID you pick (format-validated). Reuse on retries, regenerate on new user intents. See [Idempotency](/integrate/core-concepts/idempotency). | Generate and persist one key per user order. In Bash or Zsh: ```bash ORDER_KEY=$(uuidgen) ``` For fish, use this key-generation command instead: ```fish set -l ORDER_KEY (uuidgen) ``` Use the stored key for creation and every retry. Do not regenerate it when retrying the same order. The request below works in Bash, Zsh and fish. ```bash curl -X POST https://sandbox.api.nora.finance/v2/intents/onramp \ -H "X-API-Key: $NORA_API_KEY" \ -H "Content-Type: application/json" \ -H "idempotency-key: $ORDER_KEY" \ -d '{ "amountCents": 10000, "destinationWallet": "So11111111111111111111111111111111111111112", "chainId": "solana", "clientReference": "ord_123" }' ``` Example response with static/manual payment instructions (BR Code abbreviated): ```json { "id": "8f2a...", "instanceId": "4e0b...", "intentType": "onramp", "flowVersion": 1, "status": "awaiting_fiat_payment", "statusReason": null, "failureCode": null, "providerFailureCode": null, "originalFailureCode": null, "originalProviderFailureCode": null, "clientReference": "ord_123", "metadata": { "chainId": "solana", "amountCents": 10000, "…": "…" }, "expiresAt": "2026-04-22T12:30:00Z", "createdAt": "2026-04-22T12:00:00Z", "updatedAt": "2026-04-22T12:00:00Z", "pixPayment": { "brcode": "00020101021126580014BR.GOV.BCB.PIX...", "txid": "abc123", "amountCents": 10000, "expiresAt": "2026-04-22T12:30:00Z" }, "depositInstructions": null, "party": { "displayName": "Your Company", "documentMasked": "64***65", "solanaWallet": null }, "chainId": "solana" } ``` Notable response fields: - `intentType` — `"onramp"` here. - `flowVersion` — integer; pin on at least the version your code was written against. - `status` — see the lifecycle table below for the full enum. ## Render the PIX instructions Use the complete returned `pixPayment.brcode` for both the scannable QR code and the copy-and-paste field. Preserve its contents when sending it to your payment service provider (PSP). | Settlement mode | Payment instructions | Required payment capability | |---|---|---| | Manual | Static BR Code for Nora's receiving account. Nora's operators confirm receipt. | Your PSP must accept the complete static BR Code. | | Automatic | Provider-generated charge code returned by Nora. Receipt processing follows bank evidence. | Your PSP must support payment of the returned charge instrument. Validate actual provider samples before activation. | An unchanged JSON response shape does not establish payment compatibility. Do not extract a receiving key or rebuild the code. An embedded key, amount tag `54`, and a fixed BR Code layout are not guaranteed across modes. Confirm real provider samples before classifying their exact format. Use `pixPayment.amountCents` for the payment amount and `pixPayment.expiresAt` for the instruction deadline when non-null. Do not derive either value from an assumed code layout. Provider instructions can expire before the intent itself. Stop presenting expired instructions; retrieve the original intent to check its state before starting another operation. Once the unpaid intent is `expired`, a new user operation needs a fresh `idempotency-key` and, if supplied, a fresh `clientReference`. Successful creation of a payable onramp includes `pixPayment` in that same response. A creation timeout can return `503` while the original operation continues. Follow [creation recovery](/integrate/api-reference/intents#onramp-creation-recovery) with the original key and body. QR availability does not emit a webhook. Fetched intents and replays can have `pixPayment: null`: payment may already be recorded, the intent may be closed, or automatic instructions may be unavailable or expired. Rarely, a new creation also returns `201` with `pixPayment: null` when the automatic charge is paid before the response. A recorded automatic payment under review also hides the QR. Use the intent's state and the recovery guidance; a missing QR is not permission to create another charge. Automatic production admission requires explicit organization opt-in for the target environment. Opt-in defaults off: missing or disabled permission keeps new production intents manual. It must combine with every other eligibility check. Production automatic activation remains on standby; coordinate validation and activation with Nora. Each intent retains the settlement decision made at creation; changing admission permission does not convert existing intents or their replays. In the **sandbox** nobody pays: the deposit is simulated and the intent moves to `fiat_received` on its own shortly after creation, then mints. This simulation does not validate real GOWD bank execution or your PSP's support for its charge instrument. Coordinate validation with Nora before production activation. Activation requires agreement on migration scope, validation arrangements, the versioning policy, and an effective date. The [published versioning policy](/integrate/api-reference#versioning) and existing customer notice commitments continue to apply. ## Track completion Poll `GET /v2/intents/:id` or subscribe to webhooks. The full intent status enum: | Status | Terminal? | Notes | |---|---|---| | `created` | no | Accepted server-side, not yet routed. | | `requires_compliance` | no | Held for compliance review. | | `awaiting_fiat_payment` | no | Waiting for the user's PIX. | | `fiat_received` | no | PIX confirmed by the rail. | | `minting` | no | BRS being minted on-chain. | | `awaiting_onchain_transfer` | no | | | `awaiting_burn_approval` | no | (offramp) — not seen on onramp. | | `burn_approved` | no | (offramp). | | `onchain_received` | no | | | `burning` | no | (offramp). | | `scheduled` | no | (offramp). | | `paying_out` | no | (offramp). | | `completed` | yes | Terminal success. | | `expired` | yes | PIX window closed before payment. | | `canceled` | yes | | | `failed` | no | Recovery depends on the settlement mode and failure. This is an expected intermediate step in the automatic payer-mismatch refund below. Check `failureCode`; it can be `null` (for example when the destination was denied after the PIX was charged, see `metadata.destinationAuthDenialCode`), and then `statusReason` or `metadata` carries the cause. Contact Nora with the intent ID when recovery requires review. | | `refunding` | no | Nora is processing a refund. | | `refunded` | yes | Refund completed. | For an automatic onramp still awaiting payment, a single receipt with the correct amount, within the payment deadline, can trigger an automatic refund when bank evidence proves a payer CNPJ mismatch. Nora requests the full return to the original payer and does not mint from that receipt. The rejection passes through `failed` before `refunding` and `refunded`. This `failed` step is expected in the automatic refund lifecycle and does not itself require operator intervention. Continue tracking the original intent; a refund request alone does not prove that funds were returned. Late payments, incorrect amounts and additional receipts require review. An additional receipt after mint does not move the completed intent into `refunding` or `refunded`; its return requires manual reconciliation. Manual refunds require operator review, external execution and confirmation. Other failures do not guarantee an automatic refund. Partners have no public refund-start endpoint; contact Nora with the intent ID when recovery needs review. ## Gotchas - **`amountCents`, not `amount`.** Integer cents, not decimal BRL. - **Minimum R$5.00 (5 BRS).** `amountCents` below `500` is rejected at creation with a `400` — the floor mirrors the on-chain `MintConfig.min_amount`. - **Idempotency keys scope to "this user intent," not "this retry."** Regenerate on a new form submission, reuse across network-level retries. See [Idempotency](/integrate/core-concepts/idempotency). - **Response `chainId` echoes the request** (`"solana"`, `"ethereum"`, `"base"`, or `"polygon"`). - **`clientReference` is unique per environment, forever.** Reusing one answers `409 Intent with clientReference 'ord_123' already exists`, even when that intent expired. A retry with the same `idempotency-key` and body is replayed instead. - **On Ethereum, Nora reads your whitelister and the BRS token on-chain before charging.** A `destinationWallet` with no authorization fails with `400` and `message: "evm_destination_wallet_not_authorized"`; one whose daily limit is below `amountCents` gets `evm_destination_wallet_rate_limit_exceeded`; an amount outside the per-mint bounds gets `evm_mint_amount_below_minimum` or `evm_mint_amount_above_maximum`. Register the wallet through the [Wallets API](/integrate/api-reference/wallets) first. A completed Ethereum mint reports `statusReason: "EVM mint confirmed on-chain."` and the transaction hash at `metadata.mintTxSignature`; `metadata` keys are informational, not part of the versioned contract. ## See also - [Offramp intent](/integrate/flows/offramp-intent) — the reverse direction (BRS → BRL) - [Ethereum end-to-end](/integrate/flows/ethereum-end-to-end) — the Ethereum mint inside the full flow, with real responses - [Idempotency](/integrate/core-concepts/idempotency) — key lifecycle - [API Reference: Intents](/integrate/api-reference/intents) — full endpoint spec - [Intents in the dashboard](/dashboard/intents) — operator-side view