Changelog - Prava Payments Docs

ImprovementsAPI

Handle merchant checkout failures with clearer codes

Merchant checkout failures now return specific HTTP statuses and safe error codes. MERCHANT_CHECKOUT_UNAVAILABLE identifies a temporary checkout outage, while MERCHANT_CHECKOUT_FAILED can accompany an HTTP 422 or 503 response. When a merchant limits checkout requests, Prava returns retriable MERCHANT_RATE_LIMITED with a Retry-After header if the merchant supplies a valid wait time. A rejected buyer email returns INVALID_EMAIL with guidance to use a different shipping email.Review checkout errors →

FixesDashboard

See why a payment or card setup needs attention

Dashboard session results and payment journeys now distinguish card-detail validation from a payment decline, and checkout preparation failures from cardholder errors. They also show approved explanations for unsupported passkeys, device verification failures, initialization timeouts, and expired quotes. Resolved sessions no longer retain stale progress errors.

ImprovementsFixes

Complete more localized merchant checkouts reliably

Checkout preparation now recognizes Spanish card, billing, review, and final payment controls on supported merchant pages. It verifies the card payment option before continuing, while keeping review steps separate from the final payment action. This helps shoppers complete localized checkouts without changing their final amount or consent checks.

Fixes

Resolve unavailable items and delivery addresses sooner

Checkout now detects a visible sold-out-item notice without waiting for the full checkout deadline. It also checks required shipping regions and available destination countries before continuing. Applications receive the existing item or delivery error, or an ADDRESS_CORRECTION_REQUIRED hint when a merchant needs a state or province, so shoppers can correct the request sooner.Review checkout errors →

ImprovementsFixes

Find products more reliably during temporary provider issues

Shopping search now retries short-lived catalog rate limits and service errors within the existing search deadline. If a relevance provider is temporarily unavailable, only the affected result batch is retried through a fallback model. Successful batches remain available, so a brief provider issue is less likely to interrupt the full search.When two search paths need the same catalog request, Prava now shares that request within the search instead of making it twice. This reduces unnecessary provider work without changing which results are eligible.Results and product details also use cached, verified merchant display names where available. This makes merchant choices clearer and keeps the name consistent as shoppers inspect an item.

NewAPI

Approve a spending budget for repeat purchases

For supported merchant checkouts, customers can approve a cumulative spending budget once for either one exact product variant or purchases from the same merchant. Later purchases use a fresh, verified checkout total within that budget without another passkey prompt.Each purchase has its own status. A completed purchase uses the verified final amount; a known failure releases unused budget when safe, while an uncertain outcome keeps its amount reserved until reconciliation. The approval itself does not buy the setup item. In sandbox, eligible card declines can be simulated as a successful test outcome after the actual decline is recorded, without marking a merchant order as paid.

Fixes

Retry checkout after a confirmed early verification failure

When authentication or device verification fails before payment credentials are issued, a shopper can retry the checkout with a fresh verification attempt. This covers canceled authentication, failed passkey or OTP setup, and supported popup timeouts. The previous attempt must be confirmed failed before a new one starts, protecting checkouts with an uncertain or already-issued payment outcome.

ImprovementsFixes

See import duties and fees in the checkout total

When a supported merchant reports import duties or duty fees, the checkout amount breakdown now separates them from tax. It checks those charges against the merchant’s final total before accepting the checkout amount, so cross-border charges are less likely to appear as an unexplained difference at payment.

ImprovementsFixesAPI

Resolve checkout address issues with clearer guidance

Merchant checkout now returns a specific DELIVERY_UNAVAILABLE_FOR_ADDRESS error when the selected items cannot be delivered to the supplied address. Applications receive a stable, non-retriable result and a buyer-safe explanation instead of a generic temporary failure.Checkout also distinguishes an unsupported state or region with INVALID_SHIPPING_REGION. A merchant rejection of the buyer’s phone number returns the existing, non-retriable INVALID_PHONE_NUMBER code rather than a generic checkout failure. When a merchant recommends adding an apartment or unit number but can still continue, the quote remains usable and carries that suggestion rather than failing the request.Handle checkout errors →

ImprovementsFixes

Remove another recognized paid protection offer before checkout

Supported merchant checkout now recognizes an additional paid package-protection offer whose checkbox omits the price. It opts out only after the merchant’s proposal confirms the charge, then waits for an updated proposal without the add-on before continuing. Other checkout preferences remain untouched.

NewDashboard

See where a payment attempt stopped

Reseller order details now show a compact payment journey for each attempt. The journey separates Prava credential issuance, the merchant checkout result, and the final recorded outcome, making it easier to identify where an unsuccessful payment stopped.Only approved lifecycle facts appear in the dashboard. Payment credentials, provider confirmation details, and internal delivery metadata remain excluded.

FixesDashboard

Open the Production request form from the environment switcher

Choosing Production in the dashboard now takes merchants who need access directly to the Production request form. This fixes a detour to Business Details and makes the next step in going live easier to find.Prepare your integration for Production →

NewDashboard

Request and set up Production access from the dashboard

Developers can now manage the Production access journey in the Prava Dashboard. The guided request keeps saved progress, shows required business and identity information, and provides a receipt after submission.Request history and current status stay visible in the application workspace. If the review needs corrections, the dashboard identifies what to update before resubmission. Approved applications continue into Production setup and credential creation without leaving the dashboard.Prepare your integration for Production →

NewImprovementsDashboard

Explore reseller portfolio analytics and orders

Reseller workspaces now bring portfolio analytics, application health, and order discovery into the dashboard. Compare Total, Paid, and Failed orders across a chosen date range and merchant scope, inspect native-currency paid volume and failure rates, and add supporting metrics to the overview when needed.The Orders workspace supports order, reference, and session search alongside status, currency, and amount filters. Each ready application has its own Overview, Orders, Analytics, and Integration views, with contextual drill-downs into recent payment activity.Comparisons are hidden when historical evidence is incomplete rather than presenting an uncertain zero or trend. Current-period values and unaffected comparisons remain available.

ImprovementsFixesAPI

More reliable checkout completion and payment reporting

Payment completion now uses the persisted transaction amount as its source of truth and applies lifecycle changes atomically. Duplicate completion calls, concurrent callbacks, and repeated result polling return the authoritative state without decrementing limits, consuming a mandate, or completing an order more than once.Approved totals must match the original payment amount after exact decimal normalization. Quote expiry and confirmed payment failures settle into durable failed results, while a saved successful outcome cannot be downgraded by a later retry or confirmation failure.Merchant checkout now gives supported preparation flows enough time to complete before reporting a timeout, reducing premature checkout failures. Card-network confirmation uses a bounded three-attempt delivery budget with shorter per-attempt timeouts, so an uncertain confirmation cannot retry indefinitely or overwrite the saved payment outcome.Payment reporting now distinguishes these recovery cases:

PAYMENT_AMOUNT_MISMATCH - the reported total or product amount differs from the amount persisted for the transaction.
QUOTE_PAYMENT_CONFLICT - the submitted report conflicts with the payment attempt already bound to the quote.
VISA_CONFIRMATION_PENDING - the payment outcome is saved and card-network confirmation is still pending.
VISA_CONFIRMATION_RECONCILIATION_REQUIRED - automatic confirmation attempts are exhausted; the saved payment outcome remains authoritative while confirmation is reconciled.

Handle payment results → · Review error recovery →

ImprovementsFixes

Keep active card verification from restarting

Checkout now distinguishes an active card-verification session from one that failed to initialize. Once verification is ready, it has time to complete instead of being replaced by the shorter loading timeout. This prevents shoppers from being sent back to card selection while authentication is still in progress.If initialization actually fails, retrying creates a fresh verification session. Late events from the failed session are ignored, and a repeated failure keeps the error visible so the shopper can retry safely.

NewImprovements

Apply offer codes while preparing a shopping checkout

Shopping checkout can now apply an offer code while preparing a product or supported merchant checkout. Accepted reductions appear in the discount breakdown and final amount. A code can also be retried on an active quote without rebuilding the shopping session.Invalid or expired codes leave the quote usable and return a safe warning so the shopper can continue without the discount. Raw offer codes are excluded from application logs and API responses.Explore agentic shopping →

ImprovementsFixesDashboard

Move through the dashboard faster without losing your place

Merchants, applications, orders, and detail pages now open with less unnecessary loading because the dashboard fetches only the workspace being viewed. Returning to a list preserves its filters and navigation context, so users can investigate several records without rebuilding their view.Focused loading and error states keep the surrounding workspace visible while the selected view loads. Forms continue to warn before navigation when there are unsaved changes.

NewAPI

Payment results include merchant lifecycle status

GET /v1/sessions/{sessionId}/payment-result returns merchant_res when merchant lifecycle data exists. Merchant and agent results expose a normalized status and an optional merchant orderId. A completed checkout can include:

{
  "status": "completed",
  "merchant_res": {
    "status": "paid",
    "orderId": "merchant_order_123"
  }
}

Lifecycle states such as pending, prepared, prepare_failed, and needs_human remain visible. Non-quote results and sessions without merchant lifecycle data omit the field. Continue using the top-level status and canonical error for outcome handling.For sandbox simulation, merchant_res.status becomes paid after sandbox completion succeeds. observed_result retains the actual merchant outcome, including a payment failure.Read the payment-result response →

ImprovementsFixes

Faster, more reliable merchant checkout

Merchant checkout now reuses verified preparation and card-field checks when the page has not changed, reducing repeated setup before payment. Checkout information is gathered more efficiently, and payment outcome monitoring starts without waiting for unrelated navigation.Checkout also recognizes review-then-pay flows and payment buttons that include a currency total. Final amount, card-field, and consent checks still run, including opting out of marketing offers and card saving. Checkout requests human attention when the final payment action is ambiguous.

NewAPI

Test successful checkout completion with sandbox simulation

Exercise your application’s success screen and completed-order handling even when a sandbox checkout ends in a merchant payment failure. You can now request a successful payment simulation when creating a quote-backed sandbox session.Add this field to your existing POST /v1/sessions request, using your sandbox secret key:

{
  "sandbox_simulation": {
    "stage": "payment",
    "outcome": "success"
  }
}

Complete card collection and verification, then poll the payment result as usual. Once an eligible terminal payment outcome is available, Prava returns status: "completed" and completes the sandbox order and active transaction together. Any associated one-time mandate is consumed; recurring mandates remain active. Repeated result polling is idempotent.observed_result preserves the actual payment outcome and its canonical error, so you can distinguish your application’s simulated success from what happened at the merchant.Sandbox only: This supports payment-stage success for quote-backed checkout. It does not turn pending results, preparation failures, or requests for additional verification into success. The simulated completion does not settle a real merchant payment, trigger fulfillment, or emit payment callbacks or webhooks. Production, custom checkout, and mandate-setup sessions reject this option.Try sandbox simulation →

ImprovementsAPI

Payment results use consistent error codes

Merchant and agent payment-result responses now use the same terminal outcome format. Confirmed merchant payment failures return status: "failed" with a top-level error, including codes such as CARD_DECLINED, INSUFFICIENT_FUNDS, and EXPIRED_CARD. Unrecognized payment errors use PAYMENT_FAILED and a safe, consistent message.Explicit sandbox simulations additionally return observed_result for the actual terminal payment outcome. Responses use Cache-Control: no-store.Read payment-result handling → · Payment error codes →

ImprovementsFixes

Match shopping requests to the right product and quantity

Shopping discovery now recognizes equivalent measurements such as 0.75 L and 750 ml, 425 gm and 425 g, and different spellings of pack counts. It also preserves the shopper’s product wording when interpreting a request, helping distinguish a feeding bottle from an accessory such as a bottle warmer.Results stay within the eligible merchant catalogue, including when broader matching is needed. These changes improve product matching without expanding merchant eligibility.

ImprovementsFixes

Remove recognized paid protection add-ons before checkout

Supported merchant checkouts now opt out of recognized paid package-protection and return-protection extras. If a charged line remains after opting out, checkout removes that line and waits for the merchant’s updated total before continuing.The cleanup targets these recognized extras and preserves unrelated billing and required terms controls. This helps keep automatically added protection charges out of the amount presented for payment.

Fixes

Fill missing checkout names from verified billing details

Retail checkout now preserves a name already filled by the payment provider and can fill a blank cardholder-name field from the checkout’s visible billing details. Shipping details are used only when the checkout confirms that shipping is also the billing address.If a required name cannot be resolved, checkout requests human attention before clicking Pay. Hidden fields, email-derived names, and placeholder names are not used.

ImprovementsDemo

Choose shipping before paying in the Playground

The Prava Playground now lets you select another available shipping option and review its updated delivery information and final total before paying. The selection is confirmed by the merchant before payment-session creation; checkout does not rely on a locally estimated shipping price.

NewFixesDemo

Try Mastercard enrollment and saved-card authentication in the Playground demo

The Prava Playground demo now offers a Mastercard sandbox flow alongside Visa. Add the Mastercard test card, complete its hosted authentication flow, and select the saved card to try payment authentication and credential preparation.The demo wallet can retain one Visa fixture and one Mastercard fixture for the current browser. Mastercard appears only when its demo configuration is available, and a successful authentication alone does not establish a completed merchant payment.This release also fixes Visa sandbox initialization in the demo. These changes apply to the configured demo experience; general Mastercard availability in the Core API is separate.

Fixes

Prevent cached assets from blocking checkout initialization

The secure checkout iframe now bundles its logger with the versioned application asset. An older cached logger can no longer cause the ensureIframeLogger is not defined error during payment initialization. No integration change is required.

ImprovementsFixesAPI

Mexico-issued cards and enrollment retry improvements

Card eligibility: Mexico-issued cards now pass Prava’s issuing-country check. Existing issuer restrictions still apply.
Enrollment retries: If Visa verification fails to initialize before a card is provisioned, Try again now starts a fresh readiness cycle in the same enrollment session.
Card artwork: Full-enrollment completion can display the card artwork when it is available.

These improvements are available in production.Integrate card enrollment →

ImprovementsAPI

Payment results identify the card used

GET /v1/sessions/{sessionId}/payment-result now returns transactions[].card_id, the source of truth for the card bound to the transaction whether preselected or chosen during collection.
Results can report status: "processing" while payment or merchant checkout is still running. For quote-backed sessions, keep polling for the merchant’s terminal outcome; credential issuance alone does not mean the merchant order is paid.

NewAPI

Enroll a card and set up its passkey without a payment

Prepare a customer’s card for future payments in a dedicated enrollment flow. POST /v1/sessions/enroll-card now accepts enrollment_mode: "full_enrollment" and returns a session that the customer completes on Prava’s secure surface.Start with an existing vault_ref_id, or omit it to let the customer enter a card. Full enrollment provisions the card and completes its Visa enrollment and passkey setup without creating an order or transaction. The existing provision_only mode continues to return a card_id directly for an already-vaulted card.Create the session on your backend using your secret API key:

{
  "enrollment_mode": "full_enrollment",
  "user_id": "customer_123",
  "user_email": "customer@example.com",
  "integration_type": "full_checkout"
}

Open the returned iframe_url unchanged. Your backend can poll GET /v1/sessions/{sessionId}/status to distinguish a provisioned card from completed enrollment. Accept success when status is completed and outcome is fully_enrolled. Retryable failures can be retried inside the same session using the selected card.Set up card enrollment → · Poll enrollment status →

Improvements

Dashboard sandbox deployment

Clearer dashboard environment switching

The developer dashboard now coordinates environment changes across open tabs and shows a transition while the selected view refreshes. Failed switches offer a recovery action. Switching checks for unsaved edits and one-time API keys, and entering the production view asks for confirmation.This update is deployed to the sandbox-hosted dashboard. The production view is available to accounts with production access.Using dashboard environments →

NewAPI

Provision a vaulted card from your backend

Merchant integrations can now call POST /v1/sessions/enroll-card with a secret API key to provision an already-vaulted customer card. Supply the customer identity, vault_ref_id, and consent reference; the response returns the resulting card_id.This server-to-server flow creates no order or transaction. It provisions the card; passkey setup and payment authorization are separate steps.Provision a card →

ImprovementsAPI

New API keys identify their environment

Newly issued merchant keys use pk_test / sk_test prefixes for sandbox and pk_live / sk_live for production. Production key creation in the dashboard requires production access.Manage API keys →

NewImprovements

Reseller dashboard

Manage AI applications in enabled reseller workspaces

Enabled reseller workspaces in the sandbox-hosted dashboard have dedicated Overview, Applications, and Team views. With merchant onboarding enabled, submit an application, follow its review status, and respond to requested changes before activation.Authorized workspaces can inspect their applications’ orders and transactions and, with credential management enabled, create a replacement key before revoking the old one. The read-only Team view lists active members and pending invitations.Availability follows the reseller’s enabled environment and modules. Each order retains its own currency; application analytics avoid combining amounts across currencies.Open the dashboard →

ImprovementsFixes

Quote-backed embedded checkout uses the full-width layout

Quote-backed embedded checkout uses the full-width, borderless presentation of standard embedded checkout, keeping the payment surface aligned with its host page.Choose a checkout presentation →

NewAPI

Create payment sessions from an existing quote

POST /v1/sessions supports a quote-based flow: pass the quote ID and Prava resolves its merchant, products, and final total before creating the payment session. From your backend, authenticate with your merchant secret key and send:

{
  "user_id": "customer_123",
  "user_email": "customer@example.com",
  "total_amount": "49.99",
  "currency": "USD",
  "purchase_context": {
    "quote": true,
    "quote_id": "qte_..."
  }
}

Use the exact final amount and currency of your quote. A mismatch returns 409 QUOTE_SESSION_MISMATCH; an expired quote returns 410 QUOTE_EXPIRED. Omit custom in quote mode.Create a session →

FixesCLI

@prava-sdk/cli 3.2.0

CLI mandate setup uses the agent session API

@prava-sdk/cli 3.2.0 fixes prava mandate create: it now sends the agent-session request format and displays the returned approval URL. Version 3.1.0 sent the request to the merchant-session endpoint and expected a different response field.Action required: If you use 3.1.0 to create mandates, update to 3.2.0 or later.API responses also expose X-Min-CLI-Version and X-Min-Skill-Version. Set X-Skill-Name to receive the requirement for that skill. The production CLI minimum is 3.2.0.Create a mandate with the CLI →

Breaking ChangesAPI

Session purchase context has two explicit modes

POST /v1/sessions now accepts purchase_context as an object with two mutually exclusive modes: { custom: [...] } for caller-supplied merchant and product details, or { quote: true, quote_id: "qte_..." } for an existing quote.Action required for custom checkout integrations: Change purchase_context: [...] to purchase_context: { custom: [...] } on the same endpoint. Keep your existing merchant and product fields inside that array; one merchant is supported per session. Omit quote_id in custom mode and omit custom in quote mode.Create a session →

Breaking ChangesAPI

Catch invalid merchant URLs and email domains at session creation

Session creation validates merchant URLs and customer email domains earlier. Supply an HTTPS merchant URL with a valid public domain and a customer email on a routable domain. Merchant URLs are stored as their origin, with paths, queries, and fragments removed; merchant names are normalized to Visa-supported characters.Action required: Replace HTTP, localhost, IP-address, or invalid-domain merchant URLs and non-routable email domains in affected session requests.Create a session →

ImprovementsFixes

Card-art generation has bounded work and retries

Card-art generation limits concurrent work and repeated attempts to reduce interference with payment requests, including when cards without artwork are listed again.Saved cards →

Improvements

Developer dashboard

Edit your application profile and checkout brand color

After setting up a merchant in the selected environment, use Business Details in the sandbox-hosted developer dashboard to update the application name, website, and embedded-checkout brand color. These edits are also available in the production view for approved accounts. Production access remains subject to approval.Update business details →

NewImprovementsAPI

Reset saved-card passkeys while keeping the card

Cardholder session authentication can call DELETE /v1/cards/{id}/device-bindings to remove device bindings while keeping the saved card and network token. Local passkey state is cleared only after removal is verified. Shared-token bindings cannot be reset through this endpoint.Merchant default-card mutations are also scoped to the merchant’s own customers.Saved cards →

ImprovementsFixes

More reliable card entry and currency handling

Mobile layouts keep expiry fields and card-entry controls visible on narrow screens.
Card-vault connection failures have bounded retries before provisioning.
Currency handling uses the order’s supported currency throughout the payment flow.

Checkout flow →

NewImprovements

Developer dashboard

Named API keys and staged rotation

The sandbox-hosted developer dashboard lets you name API keys and see their creation date, last use, and status. New secret keys are shown once. Rotate a key by creating and saving its replacement, updating your integration, and then explicitly revoking the old key. The old key stays active until you revoke it.Key creation requires the developer role or higher; revocation requires admin access. Production views and actions require production access.Manage API keys →

ImprovementsBreaking ChangesAPI

Encrypted agent charge results and standing-mandate filtering

Action required for direct agent charge integrations: Read and decrypt encrypted_payload using the agent’s private key instead of reading plaintext credentials or dynamicData. Merchant secret-key callers still receive credentials.GET /v1/mandates also accepts standing_only=true to exclude transient checkout mandates. Charging and reporting require a merchant secret key or a direct agent signature; charging is not exposed through MCP.Charge a mandate → · List mandates →

Improvements

Developer dashboard

See card-check outcomes in order history

Order details in the sandbox-hosted developer dashboard show recorded card-check outcomes per payment attempt and a readable activity timeline, making declined and retried attempts easier to follow. Production views require production access.Inspect orders →

ImprovementsAPI

More Asia-Pacific issuing countries pass card eligibility checks

Cards issued in Australia, Hong Kong, Japan, Malaysia, New Zealand, Singapore, South Korea, Taiwan, Thailand, and Vietnam now pass the issuing-country check, alongside Canada, the US, and its supported territories. Existing issuer restrictions still apply; Mexico is covered in the September 8 update.Enroll a card →

NewAPI

Manage standing mandates and reconcile each charge

Add mandate_setup with intent: "mandate_setup" to a session to collect approval for future charges. After activation, charge the mandate without another passkey prompt. One-time standing mandates are capped at seven days; a later valid_until does not extend that window. Check validUntil before scheduling a charge.

Find the right mandate: GET /v1/mandates accepts customer_id for merchant callers, using either their external customer ID or a Prava customer ID. Responses include approvedAmount, remaining, validUntil, renewsAt, and lastCharge; the detail endpoint includes charge history. Displayed balances are derived from recorded activity; Visa enforces the spending limit.
Track each charge: POST /v1/mandates/{id}/charge creates its own order and transaction. Send a decimal-string amount and an optional reference to deduplicate retries within that mandate. Failed charges release the reference for retry. Currency comes from the mandate; an optional per-charge purchase_context remains a one-entry array.
Report the outcome: Send txn_status: "APPROVED" or "DECLINED" to POST /v1/mandates/{id}/charges/{txnId}/report to reconcile the charge and report to Visa. txn_type defaults to "PURCHASE".
Control future charging: POST /v1/mandates/{id}/pause, /resume, and /cancel manage the mandate’s Prava state. Cancellation is terminal in Prava; these controls do not revoke the underlying Visa instruction.

Charging and reporting require a merchant secret key or a direct agent signature. Charge requests are not exposed through MCP.Set up a mandate → · Charge → · Report → · Lifecycle controls →

ImprovementsFixes

Checkout retries refresh saved cards and clear old errors

Retrying checkout refreshes saved cards and clears stale error overlays so newly added cards are available on the next attempt. Embedded checkout retains the restored card list and add-card controls from the July 2 retry fix.Checkout flow →

NewMCPDocs

Prava MCP is live

Connect any MCP client to https://mcp.pay.prava.space/mcp and your agent can pay and shop with your card. One URL, OAuth sign-in, 12 tools, and a credential firewall: payment credentials never reach the agent. Start at Prava MCP.

Docs

New end-to-end guides: Add Payments to Your AI App, REST Checkout Walkthrough, and the Go-Live Checklist.
New reference pages: Errors (every code in one catalog), Testing in Sandbox, and Delete Card.
New audience pages: Your Prava Pay Dashboard for agent owners, For Merchants, Use Cases, and Compliance & Verification.
Sandbox test cards and test OTP published.
Navigation reorganized: SDK, MCP, and CLI are sibling integration methods under Developer Guide; Capabilities and FAQ have their own tabs.
Payments restructured around the public flow — what you drive vs. what Prava does for you — plus a new Glossary.
Fresh visual identity: brand fonts, light theme, imagery, and an interactive API playground backed by an OpenAPI spec.
Agent skills: prava-pay, prava-shopping, and prava-sdk-integration installable via npx skills add.
Docs MCP server at docs.prava.space/mcp and llms.txt for AI-assisted integration — see Use Prava Docs with AI.

API

POST /v1/deleteCard documented in the API reference and OpenAPI spec.

ImprovementsAPICLI

Replay agent-session requests

Direct signed-agent integrations can send an Idempotency-Key with POST /v1/sessions/agent. Reusing it for the same agent returns the original session with HTTP 200; a new session returns 201. A concurrent duplicate can return 409 DUPLICATE_EXTERNAL_ORDER_REF; retry with the same key to retrieve the original.This endpoint accepts flat total_amount, currency, merchant_name, merchant_url, merchant_country, and products fields. Read the approval link from payment_url. Use a new idempotency key for each new purchase.Use the current CLI →

NewCLI

@prava-sdk/cli 3.0.0

Shopping commands in Prava CLI v3

@prava-sdk/cli 3.0.0 adds prava shop search, product, quote, and checkout commands alongside the existing agent-linking and payment-session commands. The package also includes commands to list, add, and choose a default delivery address.Explore CLI shopping commands →

Fixes

Wait for settled shipping and tax before accepting checkout totals

Merchant checkout now waits while the merchant is still calculating tax or has not yet selected an available shipping method. This avoids accepting a plausible total that later changes when shipping or tax is applied.Checkout can also recover displayed information when network data is unavailable, and corrected address-validation errors clear when the merchant accepts the updated details.

ImprovementsFixes

Mobile verification screens fit embedded checkout

Verification and OTP steps align to the top of embedded mobile checkout, keeping the active controls easier to reach. These changes build on the May 25 responsive footer update, including iPhone bottom safe-area handling.Checkout flow →

NewAPI

Remove saved cards and refresh their lifecycle when re-saving

POST /v1/deleteCard accepts CUSTOMER_CONFIRMED for ordinary customer-requested removal and returns was_default and network_token_deleted. Shared network tokens are retained for other customers.Re-saving a removed card refreshes reused enrollment and token records for the new saved card.Delete a card →

ImprovementsFixes

Compare delivery estimates across shipping options

Merchant checkout now preserves delivery estimates for individual shipping options, including estimates supplied by merchant delivery-date apps. When an estimate is available only on the page, checkout can fill that missing information for the matching option.The selected delivery estimate stays aligned with its shipping method. Merchant-provided prices, tax, and totals remain unchanged by this delivery-information fallback.

NewImprovements

Branded embedded checkout

Set integration_type: "embedding" when creating a session for checkout that uses your stored merchant brand color. The default "full_checkout" mode provides the standalone checkout presentation.Choose a checkout presentation →

ImprovementsAPI

Automatic card defaults and Canadian card eligibility

When a card list has no default, the earliest saved card becomes the fallback, including after an explicit clear. Card lists identify that selection with is_default.Canada joins the US and its supported territories in Prava’s issuing-country check. Existing issuer restrictions still apply.List cards →

FixesAPI

Accurate payment totals and verification recovery

Payment authorization uses the full approved order total, including tax and shipping, rather than the sum of product prices alone.Visa verification initialization has timeout and retry handling so an initialization failure can surface a recoverable state.Create a session →

ImprovementsCLI

@prava-sdk/cli 2.0.0

Shorter agent approval links and clearer setup recovery

@prava-sdk/cli 2.0.0 updates prava setup to register a signed request and print a short approval link containing a server-issued link ID. Agent metadata is submitted during registration instead of being carried in the approval URL.Setup reports expired or denied links and explains when an incorrect system clock prevents registration. Polling stops when a link expires and tells you to start setup again.Link an agent →

NewAPI

Choose a default saved card

GET /v1/listCards returns is_default and places the default first. Merchant secret-key callers can set it with PATCH /v1/cards/{id}/default or clear it with PATCH /v1/cards/remove-default, passing the customer’s Prava ID in the customer_id query parameter.List cards →

Improvements

Dashboard sandbox deployment

More visible API-key creation errors

API-key creation failures now appear as notifications in the sandbox-hosted dashboard, making unsuccessful requests easier to spot while the key-creation dialog remains open.Manage API keys →

NewFixesAPI

Production enrollment milestone

Live card enrollment verified in production

Prava’s first live cardholder enrollment was verified against production Visa services. The verified flow covers session creation, hosted card verification, and enrollment for the initial production integration.Related fixes restored production API requests that had blocked merchant onboarding and corrected the Visa environment used by hosted verification.Understand the checkout flow →

NewCLI

@prava-sdk/cli 0.0.1

The first Prava CLI package

The first public @prava-sdk/cli package introduces the prava command for agent integrations. Version 0.0.1 includes prava setup, prava status, and prava sessions create, with polling for the payment-session result.Get started with the current CLI →

​Handle merchant checkout failures with clearer codes

​See why a payment or card setup needs attention

​Complete more localized merchant checkouts reliably

​Resolve unavailable items and delivery addresses sooner

​Find products more reliably during temporary provider issues

​Approve a spending budget for repeat purchases

​Retry checkout after a confirmed early verification failure

​See import duties and fees in the checkout total

​Resolve checkout address issues with clearer guidance

​Remove another recognized paid protection offer before checkout

​See where a payment attempt stopped

​Open the Production request form from the environment switcher

​Request and set up Production access from the dashboard

​Explore reseller portfolio analytics and orders

​More reliable checkout completion and payment reporting

​Keep active card verification from restarting

​Apply offer codes while preparing a shopping checkout

​Move through the dashboard faster without losing your place

​Payment results include merchant lifecycle status

​Faster, more reliable merchant checkout

​Test successful checkout completion with sandbox simulation

​Payment results use consistent error codes

​Match shopping requests to the right product and quantity

​Remove recognized paid protection add-ons before checkout

​Return to the same place in your dashboard

​Fill missing checkout names from verified billing details

​Choose shipping before paying in the Playground

​Try Mastercard enrollment and saved-card authentication in the Playground demo

​Prevent cached assets from blocking checkout initialization

​Mexico-issued cards and enrollment retry improvements

​Payment results identify the card used

​Enroll a card and set up its passkey without a payment

​Clearer dashboard environment switching

​Provision a vaulted card from your backend

​New API keys identify their environment

​Manage AI applications in enabled reseller workspaces

​Quote-backed embedded checkout uses the full-width layout

​Create payment sessions from an existing quote

​CLI mandate setup uses the agent session API

​Session purchase context has two explicit modes

​Catch invalid merchant URLs and email domains at session creation

​Card-art generation has bounded work and retries

​Edit your application profile and checkout brand color

​Reset saved-card passkeys while keeping the card

​More reliable card entry and currency handling

​Named API keys and staged rotation

​Encrypted agent charge results and standing-mandate filtering

​See card-check outcomes in order history

​More Asia-Pacific issuing countries pass card eligibility checks

​Manage standing mandates and reconcile each charge

​Checkout retries refresh saved cards and clear old errors

​Prava MCP is live

​Docs

​API

​Replay agent-session requests

​Shopping commands in Prava CLI v3

​Wait for settled shipping and tax before accepting checkout totals

​Mobile verification screens fit embedded checkout

​Remove saved cards and refresh their lifecycle when re-saving

​Compare delivery estimates across shipping options

​Branded embedded checkout

​Automatic card defaults and Canadian card eligibility

​Accurate payment totals and verification recovery

​Shorter agent approval links and clearer setup recovery

​Choose a default saved card

​More visible API-key creation errors

​Live card enrollment verified in production

​The first Prava CLI package

Handle merchant checkout failures with clearer codes

See why a payment or card setup needs attention

Complete more localized merchant checkouts reliably

Resolve unavailable items and delivery addresses sooner

Find products more reliably during temporary provider issues

Approve a spending budget for repeat purchases

Retry checkout after a confirmed early verification failure

See import duties and fees in the checkout total

Resolve checkout address issues with clearer guidance

Remove another recognized paid protection offer before checkout

See where a payment attempt stopped

Open the Production request form from the environment switcher

Request and set up Production access from the dashboard

Explore reseller portfolio analytics and orders

More reliable checkout completion and payment reporting

Keep active card verification from restarting

Apply offer codes while preparing a shopping checkout

Move through the dashboard faster without losing your place

Payment results include merchant lifecycle status

Faster, more reliable merchant checkout

Test successful checkout completion with sandbox simulation

Payment results use consistent error codes

Match shopping requests to the right product and quantity

Remove recognized paid protection add-ons before checkout

Return to the same place in your dashboard

Fill missing checkout names from verified billing details

Choose shipping before paying in the Playground

Try Mastercard enrollment and saved-card authentication in the Playground demo

Prevent cached assets from blocking checkout initialization

Mexico-issued cards and enrollment retry improvements

Payment results identify the card used

Enroll a card and set up its passkey without a payment

Clearer dashboard environment switching

Provision a vaulted card from your backend

New API keys identify their environment

Manage AI applications in enabled reseller workspaces

Quote-backed embedded checkout uses the full-width layout

Create payment sessions from an existing quote

CLI mandate setup uses the agent session API

Session purchase context has two explicit modes

Catch invalid merchant URLs and email domains at session creation

Card-art generation has bounded work and retries

Edit your application profile and checkout brand color

Reset saved-card passkeys while keeping the card

More reliable card entry and currency handling

Named API keys and staged rotation

Encrypted agent charge results and standing-mandate filtering

See card-check outcomes in order history

More Asia-Pacific issuing countries pass card eligibility checks

Manage standing mandates and reconcile each charge

Checkout retries refresh saved cards and clear old errors

Prava MCP is live

Docs

API

Replay agent-session requests

Shopping commands in Prava CLI v3

Wait for settled shipping and tax before accepting checkout totals

Mobile verification screens fit embedded checkout

Remove saved cards and refresh their lifecycle when re-saving

Compare delivery estimates across shipping options

Branded embedded checkout

Automatic card defaults and Canadian card eligibility

Accurate payment totals and verification recovery

Shorter agent approval links and clearer setup recovery

Choose a default saved card

More visible API-key creation errors

Live card enrollment verified in production

The first Prava CLI package