Frame

Connect your platform's Frame account to process credit card and ACH transactions through Preczn.

Frame is a payment processor that supports card and ACH (bank account) payments. Frame credentials are held at the platform level: your platform's Frame API keys are configured once on the Preczn connection, and each merchant is identified by the Frame account ID assigned to them.

Supported Capabilities

Supported Transaction Types

📘

ACH is sale and refund only

ACH has no authorization hold at Frame. An ACH auth is rejected with ACH is not supported for Frame authorization transactions. ACH supports sale and refund only. Use a sale instead of auth + capture, and refund an ACH transaction rather than voiding it.

A Verify request to Frame — card or bank account — is rejected with Verify is not supported for Frame. Frame offers no zero-dollar authorization; card details are validated when the first real transaction is processed.

Credentials

Frame credentials are split across two levels:

There is no per-merchant Frame secret. Every request Preczn sends to Frame authenticates with the platform secret key and is scoped to the merchant by the account ID.

Adding the Platform Connection

1. Select Connections from the left-hand navigation.
2. On the Add Connections tab, select Connect under Frame.
3. Enter a name for the connection.
4. Enter your Publishable Key and Secret Key.
5. Select Verify Connection.

⚠️

Key prefixes must match the mode

Frame serves its sandbox and production environments from the same address and tells them apart by the key prefix. A Test Mode connection requires sk_sandbox_ / pk_sandbox_ keys and a Live connection requires sk_production_ / pk_production_ keys. A mismatch is rejected before the connection is saved — for example, Invalid secret key. Test secret keys must start with the prefix "sk_sandbox_". There is no environment or URL field to set.

Verification confirms that Frame accepts your secret key. If it fails, the message tells you which case you hit:

Saving the connection also creates a Default Frame Plan for routing, and registers Preczn's webhook endpoint with Frame — see Webhooks.

Adding a Merchant's Account ID

A merchant is connected to Frame by storing the Frame account ID on their Preczn merchant connection. The account ID can be supplied three ways.

Dashboard

1. Navigate to Merchants and open the merchant.
2. In the merchant's Connections pane, select Frame.
3. Enter the Account ID and save the connection.

The merchant's Frame connection stays Unconfigured until an Account ID is present. No key or secret is collected here.

Merchant Import

Include the account ID when importing merchants via CSV, using the column header:

API Integration

Configure the account ID programmatically with the Update Connection Details endpoint:

curl --request PATCH \
  --url https://api.preczn.com/v1/merchants/{merchantId}/connections/Frame \
  --header 'Authorization: Bearer {api_key}' \
  --header 'Content-Type: application/json' \
  --data '{
    "mid": "{Frame account ID}"
}'

Request Fields

📘

The account ID is stored, not checked against Frame

Saving a merchant's Frame connection verifies the platform secret key, which is the only credential Frame authenticates. The account ID itself is not validated, so an incorrect value saves successfully and surfaces later as a transaction error. Copy it directly from Frame.

Processing Transactions

Route transactions to Frame the same way as any other connection — through a plan or a direct connection reference on the transaction. The sections below cover the behavior specific to Frame.

Transaction Records at Frame

Frame records a sale or refund as a transfer and an authorization as a charge intent. The processorTransactionId on the Preczn transaction is the id of the matching Frame object, so it can be used to find the transaction in Frame.

Voids

Only an authorization can be voided. A sale has no equivalent operation at Frame, so a void against one is rejected with Frame cannot void a transfer-backed sale transaction; use refund instead. To reverse a sale, issue a Refund.

Captures

Captures may be partial, and an authorization may be captured more than once up to the authorized amount. Voiding after a partial capture releases the uncaptured remainder.

Pending Transactions

Frame confirms some transactions asynchronously, so a Frame transaction can return with a status of P (Pending) and settle to A (Approved) or D (Declined) later. This is normal for ACH, where the sale is submitted into the ACH network and the outcome arrives days later, and it can also happen on a card transaction that Frame is still processing.

Treat P as "not yet an outcome" — do not fulfill an order on it. Subscribe to the transaction.approved, transaction.declined, and transaction.errored webhook events to be notified when the transaction reaches its final status, or poll Get Transaction.

An ACH return arrives as a decline on the original transaction rather than as a separate record, on standard NACHA timing.

3D Secure

Frame authorizations are performed server-to-server, so a card that requires a 3D Secure challenge cannot be completed. The transaction is declined with 3D Secure challenge required; not supported for server-side Frame authorization.

Timeouts

Frame does not support idempotency keys, so a request that never returns a response cannot be safely resent. When this happens, Preczn tries to recover the real outcome by looking the transaction up at Frame. If the outcome cannot be confirmed, the transaction is recorded with a status of E (Error) and this message:

Processor request timed out before a response was received. The transaction may or may not have been processed by Frame. Verify the transaction status with Frame before retrying to avoid duplicate processing.

Do not blindly retry an E on Frame — confirm in Frame first, or you risk charging the cardholder twice.

Data Not Sent to Frame

Frame's API has no equivalent for the following, so these values are accepted by Preczn and used elsewhere but never reach Frame:

• Metadata
• Dynamic Statement Descriptors
• Level II and Level III data

Frame also returns no raw AVS or CVV result codes. Send the billing address and CVV as usual — Frame uses them in its decision — but an address or CVV mismatch surfaces as a decline reason rather than as a response code.

Transaction Status Mapping

Frame's status vocabulary differs between transfers and charge intents, and the same word can mean opposite things across the two. Preczn maps each to a transaction status of A, D, or P.

Sale and Refund

Auth, Capture, and Void

A status Preczn does not recognize is treated as Pending rather than as an approval or a decline, so an unfamiliar Frame status never produces a false outcome. A status of E (Error) always means the request itself failed — a connectivity problem, a rejected request, or a timeout — never an issuer decision.

Webhooks

Frame webhooks are configured for you. When you save or update the platform connection, Preczn registers its own endpoint with Frame, subscribes to the transfer and charge intent events it needs, and stores the signing secret Frame issues. Every event is signature-verified before it is processed.

There is nothing to configure in the Frame dashboard, and nothing merchant-specific to maintain — one endpoint per platform connection serves all of your merchants.

⚠️

Don't hand-edit the Preczn endpoint in Frame

Frame issues an endpoint's signing secret once and never displays it again, so editing or rotating Preczn's endpoint inside the Frame dashboard leaves Preczn with a secret that no longer matches and Frame's events will be rejected. If the endpoint is deleted, save the platform connection again in Preczn and it is re-registered with a fresh secret.

To receive transaction updates in your own application, subscribe to Preczn's transaction webhooks rather than to Frame's.

Testing in the Sandbox

1. Add the Frame connection in Test Mode using your sk_sandbox_ and pk_sandbox_ keys.
2. Set a test merchant's Account ID to a Frame sandbox account.
3. Send transactions using the standard Preczn test cards and test bank accounts — Preczn translates them to Frame's sandbox values automatically, so no Frame-specific test data is needed.

Test and Live connections are configured separately, and Preczn routes to the matching Frame environment based on the mode the transaction runs in.

FAQ