Frame

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

Frame is a payment processor that supports card, ACH (bank account), Apple Pay, and Google Pay 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

CapabilityStatusNotes
Credit Card TransactionsSupportedSale, auth, capture, void, refund, and verify
ACH (Bank Account) TransactionsSupportedSale and refund only
Merchant OnboardingNot supportedMerchant accounts are created with Frame directly, then linked in Preczn
Apple Pay / Google PaySupportedSale and auth. Verify is not supported (see Wallet Payments)

Supported Transaction Types

TypeCardACHDescription
Sale✅✅Authorize and capture in a single request
Auth✅—Authorize only (hold funds without capturing)
Capture✅—Capture all or part of an authorization
Void✅—Release an authorization hold (see Voids)
Refund✅✅Return funds from a sale or a capture
Verify✅—Zero-amount card authorization; no funds are held or moved
📘

ACH verify is not supported

Frame can't verify a bank account. An ACH verify routed to Frame is rejected with HTTP 400, processorCode ACH_UNSUPPORTED_TRANSACTION_TYPE, and ACH is not supported for Frame authorization transactions. ACH supports sale and refund only. Run the sale directly; the bank account is validated when the sale is processed. For the ACH transaction types every connection supports, see ACH Transactions.

A card Verify runs at Frame as a zero-amount card authorization. Preczn always sends an amount of zero, whatever the request carries, so no funds are held or moved. A bank account or wallet payment can't be verified through Frame.

Credentials

Frame credentials are split across two levels:

CredentialLevelWhere it comes from
Publishable KeyPlatformFrame dashboard — pk_sandbox_… / pk_production_…
Secret KeyPlatformFrame dashboard — sk_sandbox_… / sk_production_…
Account IDMerchantThe Frame account ID for that merchant

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 with HTTP 400 before the connection is saved — for example, processorSecret must be a Frame secret key (sk_sandbox_*/sk_production_*) matching this connection's isTestMode. 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:

MessageWhat it means
Invalid API credentialsFrame rejected the secret key. Check for a copy error or a revoked key.
Unrecognized Frame secret key formatThe value is not an sk_sandbox_ / sk_production_ key — a publishable key pasted into the Secret Key field lands here.
Frame service unavailable, please try againFrame returned a server error. The key was not rejected; retry.
Frame secret key environment does not match isTestModeThe secret key's prefix doesn't match the connection's mode. See the key prefix note above.

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:

ColumnDescription
account_idThe Frame account ID for this merchant

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

FieldTypeRequiredDescription
midstringYesThe Frame account ID for this merchant
📘

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

The processorTransactionId on a Frame transaction is the id of the matching Frame record. A sale or auth and every capture, void, and refund that follows it share the same processorTransactionId, so one id finds the whole history in Frame.

Wallet Payments

Apple Pay and Google Pay payments can be sent to Frame as a sale or an auth. A wallet auth is captured, voided, and refunded the same way as a card auth. Collect the payment as described in Apple Pay on the Web or Google Pay for Web.

Preczn checks each wallet payment before sending it to Frame. A payment that fails a check is rejected with HTTP 400 and the processorCode shown:

processorCodeMessageCause
WALLET_UNSUPPORTED_TRANSACTION_TYPEWallet payments are not supported for Frame verify transactions.A verify was sent with a wallet payment. Run the sale or auth directly.
WALLET_INVALID_AUTH_METHODGoogle Pay authentication method is missing or unsupported.The Google Pay authentication method is missing or is not CRYPTOGRAM_3DS or PAN_ONLY.
WALLET_CRYPTOGRAM_REQUIREDA wallet cryptogram is required for this payment.An Apple Pay payment, or a Google Pay CRYPTOGRAM_3DS payment, arrived without its cryptogram.
WALLET_BILLING_ADDRESS_REQUIREDA complete billing address is required for wallet payments.The billing address is missing a street address, city, region, or postal code, or has an unrecognized country.
WALLET_TOKEN_EXPIREDThe wallet token is expired or has an invalid expiration.The Apple Pay payment has expired. Ask the customer to approve it again.
WALLET_AMOUNT_MISMATCHThe transaction amount does not match the wallet token amount.The amount is not exactly what the customer approved in Apple Pay.

A Google Pay PAN_ONLY payment is sent without a cryptogram, so Frame must enable it on your Frame account before it can be processed.

Captures

Capture an auth by sending its transactionId. Without an amount, the remaining authorized amount is captured. With a lower amount, only that amount is captured and authorization.partial is true. An auth can be captured more than once, up to the authorized amount. Once an auth has been voided, a capture against it is rejected with Auth already voided. Capture is not allowed.

Voids

Only an authorization can be voided. Voiding an uncaptured auth releases the full hold. Voiding after a partial capture releases only the uncaptured remainder, reported in approvedAmount with authorization.partial set to true. A fully captured auth is reversed with a refund of the capture.

A sale has no equivalent operation at Frame, so a void against one returns a status of E with Frame cannot void a transfer-backed sale transaction; use refund instead. To reverse a sale, issue a Refund. A void against a capture is rejected with Transaction type does not support void.

Refunds

Refund a sale or a specific capture by sending its transactionId. An auth itself is never refunded; a refund against one is rejected with Transaction type does not support refund.

  • Without an amount, the remaining amount of that sale or capture is refunded.
  • With an amount, only that amount is refunded and authorization.partial is true. Partial refunds can be repeated up to the original amount. An amount above the original is rejected with Amount to refund should be equal or less than the original transaction.
  • Refunding one capture of an auth doesn't affect its other captures.

If a capture or refund is sent while another capture or refund on the same Frame transaction is still running, it is rejected with HTTP 409 and Another operation on this transaction is in progress; retry shortly. Nothing is sent to Frame; retry after the other operation finishes.

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. A sale, auth, or verify that hits a challenge is declined with processorCode requires_3d_secure and processorMessage 3D Secure challenge required; not supported for server-side Frame payments.

Timeouts

When Frame doesn't respond in time, the transaction is recorded with a status of E (Error). Whether it is safe to retry depends on the transaction type.

Sale, auth, and verify. Preczn passes your Idempotency-Key to Frame. If the original request carried an Idempotency-Key header, retry with the same key and Frame returns the original result instead of charging again. The error message is:

Processor request timed out before a response was received. The transaction may or may not have been processed by Frame. Retrying with the same Preczn idempotency key is replay-safe and returns the original result without duplicate processing.

If the original request had no Idempotency-Key, confirm the outcome in Frame before retrying.

Capture, refund, and void. These can't be safely resent. Preczn tries to recover the real outcome by looking the transaction up at Frame. If the outcome can't be confirmed, the error message is:

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.

Confirm in Frame first, and retry only if the capture, refund, or void didn't happen.

A status of E with Frame credential environment does not match the requested mode means the platform connection's key prefix doesn't match the mode the transaction ran in. Correct the keys on the platform connection.

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:

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

Preczn maps the payment status Frame reports to a transaction status of A, D, or P. On an approved or pending transaction, authorization.processorMessage carries Frame's status as-is.

Frame payment statusPreczn statusWhat it means
succeededA ApprovedFunds captured
requires_captureA ApprovedAuthorization hold placed
refundedA ApprovedRefund completed
canceledA on a void, D on anything elseA successful void, or a payment Frame canceled
failedD DeclinedDeclined; processorCode carries Frame's reason. Also the ACH return status
requires_3d_secureD Declined3D Secure challenge required (see 3D Secure)
requires_confirmation, incomplete, requires_account, requires_payment_methodP PendingStill in flight; a later update resolves it

A declined transaction carries Frame's decline reason in processorCode and processorMessage. Soft declines, such as insufficient_funds, do_not_honor, try_again_later, or processing_error, may succeed on a later retry. Hard declines, such as stolen_card, lost_card, expired_card, fraudulent, or do_not_try_again, won't change on retry; ask the customer for a different payment method. Frame approves or declines the full amount and never returns a partial approval.

A refund, reversal, or dispute that follows an approved sale or capture never changes the original transaction's status.

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 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. An Apple Pay or Google Pay payment is processed with a Frame test card of the same card brand, so wallet test transactions approve.

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

FAQ

Do merchants need their own Frame API keys?

No. Frame keys are held on the platform connection, and one pair of keys serves every merchant. The only Frame value stored on a merchant is their Account ID, which tells Frame which account a transaction belongs to.

Why was my connection rejected when the keys are correct?

Check that the key prefix matches the mode of the connection. A Test Mode connection only accepts sk_sandbox_ and pk_sandbox_ keys; a Live connection only accepts sk_production_ and pk_production_. Frame serves both environments from the same address and identifies the environment purely from the prefix, so Preczn rejects a mismatched pair before saving rather than authenticating against the wrong environment.

Can I run a zero-dollar verification to validate a card or bank account?

Cards, yes. A Verify routed to Frame runs as a zero-amount card authorization, so no funds are held. Bank accounts and wallet payments can't be verified through Frame; a bank account is validated when the first sale is processed.

Why can't I void a sale?

Frame has no cancel operation for a sale — only an authorization can be voided. Refund the sale instead. A void against a Frame sale returns Frame cannot void a transfer-backed sale transaction; use refund instead rather than silently doing nothing.

My transaction came back Pending. What do I do?

Wait for the final status; don't treat Pending as an approval. Frame confirms some transactions asynchronously — always for ACH, and sometimes for cards — and Preczn updates the transaction when Frame reports the outcome. Subscribe to the transaction.approved, transaction.declined, and transaction.errored webhook events, or poll Get Transaction. Once a transaction reaches Approved or Declined, a late Pending update can never move it back.

A transaction has been Pending far longer than expected. Why?

Most Pending transactions resolve on their own when Frame reports the outcome. A transaction held for Frame's fraud review stays Pending until Frame approves or declines it. If one doesn't resolve, check the transaction in the Frame dashboard, and contact Preczn support if the two don't agree.

A transaction errored with a timeout. Is it safe to retry?

It depends on the type. A sale, auth, or verify that was sent with an Idempotency-Key can be retried with the same key, and Frame returns the original result instead of charging again. A capture, refund, or void can't be safely resent, so confirm in the Frame dashboard first and retry only if nothing happened. See Timeouts.

Can I send Apple Pay or Google Pay transactions to Frame?

Yes, as a sale or an auth. A few rules apply:

  • Every wallet transaction needs a complete billing address.
  • An Apple Pay transaction's amount must exactly match the amount the customer approved, and the Apple Pay payment must not have expired.
  • A Google Pay PAN_ONLY payment is sent without a cryptogram, so Frame must enable it on your Frame account first.
  • Verify isn't supported for wallet payments on Frame.

See Wallet Payments for the rejection each rule produces.

Does my transaction metadata appear in Frame?

Yes. Preczn sends your transaction metadata to Frame on sale, auth, and verify transactions. It isn't sent on capture, refund, or void. Frame accepts metadata values up to 100 characters, so Preczn shortens longer values on the Frame record only. Preczn stores and reports the full value.

Preczn also attaches its own reference to each Frame transaction, which is what lets a timed-out request be matched back to the transaction it created.

Do I need to configure webhooks in Frame?

No. Preczn registers and maintains its own Frame webhook endpoint when you save the platform connection, including the signing secret. Leave that endpoint alone in the Frame dashboard; if it is removed, saving the Preczn connection again re-creates it. To receive updates in your own systems, use Preczn webhooks.


Did this page help you?