OpenPermit Docs | Builder integration guides

Receipt verification, canonical hashes, redaction helpers, and typed SDK errors.

Primitives are exported from @openpermit/sdk/primitives:

import {
	canonicalizeMandate,
	getMandateId,
	hashResource,
	redactPaymentMetadata,
	verifyReceipt,
} from '@openpermit/sdk/primitives';

Use typed errors from @openpermit/sdk/errors to handle policy and payment failures:

import {
	getOpenPermitProblemActions,
	getOpenPermitProblemDisplay,
	normalizeOpenPermitProblem,
	OpenPermitApiError,
	OpenPermitPaymentRequiredError,
	OpenPermitPolicyError,
} from '@openpermit/sdk/errors';

try {
	await paidFetch('https://seller.example/paid/data');
} catch (error) {
	if (error instanceof OpenPermitPolicyError) {
		console.error(error.policyDecision);
	}
	if (error instanceof OpenPermitPaymentRequiredError) {
		console.error('unsupported or malformed payment challenge');
	}
	if (error instanceof OpenPermitApiError) {
		const problem = normalizeOpenPermitProblem(error.problem);
		const display = getOpenPermitProblemDisplay(problem);
		console.error(error.status, display.title, display.primaryAction);
	}
}

Problem contract

OpenPermit APIs use RFC 9457 problem details and add stable OpenPermit extension fields:

code: stable machine code. Integrations should branch on this, never on provider strings.
category: buyer_action_required, seller_action_required, provider_unavailable, policy_denied, payment_pending, openpermit_configuration_error, or invalid_request.
actor: buyer, seller, provider, openpermit, or agent.
retryable: whether retrying the same seller continuation can succeed after the action is completed.
payment: chain, token, payee, payer, amount, balance, and atomic amount metadata when relevant.
nextActions: typed actions such as fund_wallet, refresh_permission, wait_and_retry, or contact_seller.

The SDK does not invent customer actions from provider strings or incomplete problem payloads. If an error is actionable, OpenPermit must return the action in nextActions.

Common codes:

Code	Actor	Integrator display
`payment_payer_insufficient_balance`	buyer	Ask the buyer to fund the payer account with the required token amount on the listed chain.
`payment_permission_missing`	buyer	Ask the buyer to approve the OpenPermit payment permission.
`payment_permission_expired`	buyer	Ask the buyer to refresh the permission through the seller setup link.
`payment_permission_stale`	buyer	Ask the buyer to re-open the seller setup link and approve a fresh permission.
`payment_budget_exceeded` / `payment_amount_exceeds_mandate`	buyer	Ask the buyer to update the mandate budget or basket amount.
`payment_execution_in_progress`	openpermit	Show a pending state and retry the same seller continuation after the retry interval.
`payment_facilitator_unavailable`	provider	Show a retryable provider issue; do not ask the buyer to create a new mandate immediately.
`seller_quote_amount_mismatch`	seller	Tell the seller integration to retry with the original checkout session and quote.
`seller_continuation_missing`	seller	Tell the seller to include a session-backed `merchantContinuationUrl`.
`token_or_chain_mismatch`	seller	Tell the seller to fix resource payment metadata.

For checkout pages, use the display helper instead of parsing problem strings:

import { getOpenPermitProblemDisplay } from '@openpermit/sdk/errors';

const display = getOpenPermitProblemDisplay(openPermitProblem);

return {
	title: display.title,
	body: display.description,
	rows: display.details,
	primaryAction: display.primaryAction,
};

Raw facilitator/provider messages are diagnostic data for OpenPermit logs and support. They are not part of the public contract and should not be shown as the main customer error.

Primitives and Errors

Problem contract

On this page