Developers
API v1 Talk to sales
Noria API

Financial infrastructure,
designed to be integrated.

One predictable REST API for accounts, instant payments, boleto, transfers, balances and event delivery. Every financial operation is scoped, traceable and safe to retry.

Make your first request Explore the API
create-pix-invoice.sh 
curl https://api.development.noriapay.com.br/v1/pix-invoice \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Access-Id: $ACCESS_ID" \
  -H "Access-Time: $ACCESS_TIME" \
  -H "Access-Signature: $SIGNATURE" \
  -d '{
	    "externalId": "citadel-invoice-84291",
	    "amount": 24990,
	    "expires": "2026-08-12T18:00:00.000000+00:00",
	    "payer": {"name": "Rick Sanchez", "taxId": "12345678901"}
	  }'
201 Createdrequest accepted
Why key pairs

Your private key
should stay yours.

Traditional API keys are shared secrets: both sides must hold the same credential. Noria uses Ed25519 key pairs so your systems sign requests without ever sending us the private key.

API keyShared secret
Your serversame secretAPI provider

The credential must exist on both sides. A database leak can expose something that authenticates requests.

Ed25519 key pairAsymmetric
Private keysignature onlyPublic key

Your private key never leaves your infrastructure. Noria stores only material that can verify, never create, a signature.

01

No shared credential

A compromise on our side cannot reveal a secret capable of signing requests as your project.

02

Request integrity

The method, path, query and body hash are signed together. Any change invalidates the request.

03

Rotation without downtime

Register a second public key, move traffic gradually and revoke the previous key after the rollout.

01 · Get started

From credentials to a live request.

Your API project belongs to one environment and exactly one workspace, with explicit scopes and optional source IP restrictions. Register an Ed25519 public key and keep the private key in your own infrastructure.

01

Create an API project

Choose an environment, grant only the required resource scopes and bind the project to exactly one workspace.

02

Register a public key

Generate an Ed25519 key pair. Send the base64 public key to Noria and retain the private key securely.

03

Sign every request

Build the canonical request, sign it with Ed25519 and send the three access headers to the gateway.

Development base URLhttps://api.development.noriapay.com.br
02 · Authentication

Signed at the edge.

Financial requests use Ed25519 signatures. Noria stores public keys only, so private signing material never needs to leave your systems.

Keep private keys server-side.

Never sign requests in browsers or mobile applications. Use a trusted backend and rotate keys with an overlap window.

Required headers

Access-Id

project/{projectId}/workspace/{workspaceId}

Access-Time

RFC 3339 UTC timestamp within the accepted five-minute window.

Access-Signature

Base64-encoded Ed25519 signature of the canonical request.

Protect the signing boundary

Authentication is only as strong as the system holding the private key. Treat that boundary as financial infrastructure.

01
Keep the private key out of source and logs.

Never send it to Noria or another provider. Prefer an HSM or managed key service; otherwise use an encrypted secret manager with narrowly scoped runtime access.

02
Bind credentials to expected network paths.

Register only the public egress addresses that will call the API. Use the smallest practical CIDR ranges and update the allowlist before changing infrastructure.

03
Rotate before you need to.

Maintain a documented rotation schedule and rehearse revocation. The two-key overlap window lets you replace a key without interrupting traffic.

Signed cURL · Pix invoice
set -euo pipefail
umask 077

PROJECT_ID="70be4b17-31f4-4f5d-8f73-6a2c9d0e1845"
WORKSPACE_ID="3bd90fa1-7c24-4e68-a912-8f3b5d6c7021"
ACCESS_ID="project/${PROJECT_ID}/workspace/${WORKSPACE_ID}"
ACCESS_TIME="$(date -u +"%Y-%m-%dT%H:%M:%S.000000+00:00")"
METHOD="POST"
REQUEST_PATH="/v1/pix-invoice"
QUERY=""
BODY="$(cat <<'JSON'
{
  "externalId": "citadel-invoice-84291",
  "amount": 24990,
  "expires": "2026-08-12T18:00:00.000000+00:00",
  "payer": {
    "name": "Rick Sanchez",
    "taxId": "12345678901"
  },
  "description": "Portal fluid refill",
  "tags": ["citadel", "portal-gun"]
}
JSON
)"

BODY_SHA256="$(
  printf '%s' "$BODY" |
    openssl dgst -sha256 -r |
    awk '{print $1}'
)"
CANONICAL="$(
  printf '%s\n%s\n%s\n%s\n%s\n%s' \
    "$ACCESS_ID" \
    "$ACCESS_TIME" \
    "$METHOD" \
    "$REQUEST_PATH" \
    "$QUERY" \
    "$BODY_SHA256"
)"
CANONICAL_FILE="$(mktemp)"
trap 'rm -f -- "$CANONICAL_FILE"' EXIT
printf '%s' "$CANONICAL" > "$CANONICAL_FILE"
SIGNATURE="$(
  openssl pkeyutl \
    -sign \
    -rawin \
    -inkey ed25519-private.pem \
    -in "$CANONICAL_FILE" |
  openssl base64 -A
)"

curl "https://api.development.noriapay.com.br${REQUEST_PATH}" \
  -X "$METHOD" \
  -H "Content-Type: application/json" \
  -H "Access-Id: $ACCESS_ID" \
  -H "Access-Time: $ACCESS_TIME" \
  -H "Access-Signature: $SIGNATURE" \
  --data-raw "$BODY"
Run locally

Requires OpenSSL 3 and an Ed25519 private key at ed25519-private.pem. The empty QUERY variable creates canonical line 5; BODY is hashed and sent unchanged. The private temporary file is removed automatically.

03 · Conventions

Rules that stay the same.

The resource changes. The contract does not. These conventions apply across the public financial API.

ID

Identifiers

Machine identifiers are lowercase UUID v4 values. Client references use externalId.

$

Amounts

Money is an integer in the currency's smallest unit. 24990 means BRL 249.90.

T

Timestamps

RFC 3339, UTC and microsecond precision: 2026-08-11T19:24:10.182001+00:00.

↻

Safe retries

Reuse the same externalId for a retried write. Do not generate a new reference per attempt.

→

Pagination

Lists return an opaque cursor. Send it unchanged with a limit from 1 to 100.

Aa

Fields

JSON fields use English camelCase. Unknown request properties are rejected.

04 · Resource lifecycles

Status is part of the contract.

Resources move through explicit states. Terminal states do not move again unless a transition is shown below; webhooks announce the same business changes asynchronously.

In progress Successful Needs attention Terminal
P
Pix invoice

Collection lifecycle

creating→pending→paid→refunded
From creating or pending
expiredcancelled

pendingProvider may appear while provider confirmation is uncertain; it accepts the same terminal outcomes as pending.

C
Checkout session

Hosted payment lifecycle

open→processing→completed
Terminal alternatives
expiredcancelledfailed

The synchronous Pix response is only a UI fast path. Treat checkout-session.completed or a server-to-server session read as the canonical confirmation.

B
Boleto

Charge lifecycle

creating→pending→settled
Provider terminal outcomes
expiredcancelled

Barcode data is available after provider issuance. Settlement adds the corresponding transaction identifier.

T
External transfer

Payout lifecycle

creating→processing→completed
Alternative outcomes
pendingfailed

pending means the provider outcome is uncertain. Reconciliation later moves the resource to completed or failed.

Account

Account lifecycle

provisioning→review→active
Provider decisions
suspendeddeniedclosed

Only active accounts may initiate financial writes. Account changes are exposed through the account audit log.

⌁
Webhook delivery

Delivery lifecycle

pending→processing→delivered
Failed delivery
pendingdead

Retries use exponential backoff. A manual resend returns a dead delivery to pending with a fresh attempt sequence.

05 · Errors

Errors are always actionable.

Every error response contains an errors array, even when only one condition failed. Use code for program logic and message for display.

400Malformed request or cursor
401Missing, expired or invalid signature
403Workspace, IP or scope denied
409Conflict or replayed request
422Valid JSON with invalid business data
503Temporary dependency or gateway failure
422 Unprocessable Entity
{
  "errors": [
    {
      "code": "invalidAmount",
      "message": "The amount must be greater than zero."
    }
  ]
}
API reference

Public resources, one contract.

Only routes available through the public gateway are documented here. Expand any operation to inspect its complete request and response contract. Internal callbacks, workers and service-to-service commands are intentionally excluded.

C
Hosted payments · private beta

Noria Checkout

Create an immutable server-side cart and send the buyer to Noria's hosted Checkout. Pix is available today; the session contract is designed to accept additional payment methods later.

Create sessions only from your backend.

The browser or mobile app sends an order reference to your server. Your server loads the authoritative items and amounts, signs the Noria request and returns only sessionId, checkoutUrl, clientSecret, expiresAt and returnState. Put the client secret in the URL fragment, never in a path or query string.

P
Money movement

Pix invoices

Create dynamic QR code invoices and track them from issuance through payment, expiration, cancellation or refund.

B
Money movement

Boletos

Issue boleto charges, expose barcode data to your customer and follow settlement through the same resource.

T
Money movement

Transfers

Send funds to Pix keys or bank accounts, or move balances instantly between workspaces in the same organization.

↔
Financial state

Transactions & balances

Read the financial projection produced by the ledger. Transactions are immutable; balances represent the current workspace position.

Platform

Accounts

Retrieve the financial account and its lifecycle audit log for the authenticated organization.

W
Platform

Workspaces

Segment an organization into operational balance scopes while preserving centralized ownership and access control.

⌁
Event delivery

Webhooks

Subscribe HTTPS endpoints to financial events. Deliveries are persisted before dispatch and retried with exponential backoff.

Checkout events

Subscribe to checkout-session.completed, checkout-session.expired, checkout-session.cancelled and checkout-session.failed. A client callback is only a UX signal; fulfill an order after a verified webhook or an authenticated session read reports completion.

●
Streaming · private beta

NoriaLive & OBS

Receive Pix contributions in the Noria account and display confirmed alerts in OBS. Channel URLs are generated dynamically for each workspace from the Marketplace dashboard.

Alert overlay

Add the dashboard's OBS URL as a Browser Source at the same size as the base canvas, normally 1920 × 1080. Keep the background transparent.

QR widget

Add the separate QR Browser Source at 520 × 640. It opens the channel's contribution page, where the viewer chooses value, nickname and message; it is not a static Pix code.

Capability URL

Treat the overlay URL as a read secret. Do not publish it in chat, analytics, tickets or screenshots. Copy it again from the dashboard after any rotation.

Confirmation

An alert appears only after the Pix cash-in is confirmed by the ledger and projected as a transaction. A transparent source while no alert exists is expected.

OBS does not need a Noria plugin.

Use the native Browser Source, leave “Local file” disabled and keep “Shutdown source when not visible” disabled. Reuse the same existing source in multiple scenes to avoid duplicate polling.

K
Trust & verification

Verification keys

Retrieve Noria's environment public key to verify every webhook signature before processing its payload.

Ready to build?

Start in development.
Ship with confidence.

Talk to our team to receive an API project, scopes and development credentials for your integration.

Request API access
Copied to clipboard