Fulfillment and Recovery

Naven records payment truth but does not modify your application's credits, orders, or subscriptions. Your backend must confirm settlement and fulfill the business outcome exactly once.

Recommended local order

id
user_id
amount_usd_cents
status
naven_payment_intent_id unique nullable
credited_at nullable
created_at
updated_at

Use your local order ID as the Naven externalId. Use your application user ID as customerRef when it helps correlation, but do not treat customerRef as authentication.

Safe confirmation transaction

When your backend queries Naven and receives status: settled:

1. Lock or atomically update the local pending order.
2. Verify the Naven amount and intent ID match the local order.
3. Grant credits or fulfill the order.
4. Mark the local order fulfilled and set credited_at.
5. Commit all changes in one local database transaction.

A unique naven_payment_intent_id and a conditional pending → fulfilled update prevent double crediting when the browser, user, or job retries.

Recovery

If payment succeeds but your application times out before fulfillment, query:

GET /v1/payment-intents/:intentId
Authorization: Bearer naven_api_...

When the response is settled, retry the same idempotent local fulfillment transaction. Your application does not need to scan the chain.

Treat settling as retryable. Do not create a replacement Payment Intent with a new externalId while the original outcome is uncertain.

Naven automatically reconciles long-running Robinhood USDG settlements. An operator may also call POST /v1/payment-intents/:intentId/reconcile with the Project API key; repeated calls are safe.