Before you start
You need:- Cards enabled on your project. Ask your account manager to enable them. Until they’re enabled, card registration, quotes, and transactions fail with
422 CardNotEnabledForProject. - An individual customer. Create the customer with
type: "individual",firstName, andlastNameas shown in Customer onboarding. The card is registered under that name. Other customer types are rejected with422 AccountTypeRequirementsNotMet. - A secret API key and secret (
sk_sdbx_…orsk_live_…) for your server. See Get started. - A publishable key (
pk_sdbx_…orpk_live_…) for the browser. See Get a publishable key. - Access to the OMS SDK packages.
@polygonlabs/oms-core,@polygonlabs/oms-card, and@polygonlabs/oms-riskare not available from the public npm registry. Contact us to request access.
Get a publishable key
A publishable key identifies your project in the browser. Unlike your secret key, it is safe to ship in page code.- In the OMS Dashboard, open API Keys.
- Create a Publishable key for the environment you’re building in, sandbox or production.
- Add the origin of each page that shows the card form.
A key only works in the environment it was created for, so a sandbox publishable key pairs with a sandbox secret key.
Register a card
The SDK renders the secure card fields, collects the fraud-screening signals, and submits everything in one step.1
Install the packages
The
/react entry points require React 18 or newer. Your secret key never goes in any of these packages; it stays on your server. You don’t need a server SDK: the next step shows the REST call and the optional @polygonlabs/oms-api client for JavaScript and TypeScript backends.2
Add a customer token route to your server
The SDK calls this route at least twice on every submit: once to start the fraud-screening session and once to authorize the card write. The route receives Tokens expire after one minute, so create a fresh one for every call. Don’t prefetch or cache them. Token creation takes no
{ customerId } from the browser. It must:- Authenticate your own signed-in user, with your usual session and CSRF protections.
- Refuse the request if
customerIdisn’t the OMS customer ID stored on that user’s record. An ID sent by the browser is not proof that the user owns it. - Create a token for that customer with your project access token (see Get started) and return the
{ token, expiresAt }response unchanged.
@polygonlabs/oms-api package for a typed API client: it signs in with your secret key and API secret and creates the token for you, and it refuses to run in a browser. For other languages, call the REST endpoints directly with your language’s HTTP client. Both variants below do the same thing.Idempotency-Key.3
Create the OMS client and render the form
Create one
OMS object per page with your publishable key and the risk client, and wrap your app in OMSProvider:DebitCardForm includes the secure card fields, billing address inputs, inline validation, a status message, and submit and clear buttons. Fraud-signal collection starts when OMSProvider mounts. One page serves one customer; signing in as someone else needs a page reload.To style the fields, translate the text, or use your own layout, see Customize the card form.4
Handle the result
onSuccess fires when OMS accepts the card and returns its ext_ ID. Accepted means stored, not yet usable: wait until the card is active before quoting.The form shows field errors and a status message itself. To react in your own UI, pass onStateChange and read state.status, which is { code, tone, message } or undefined. Branch on code and show message. The codes fall into four groups:- Wait.
loading,submitting, andclearingmean work is in progress.blockedmeans no action is available yet, for example before the fields have mounted or before a customer is identified. - The customer acts.
correct_fields: OMS or the form rejected a card or billing value, and the customer fixes it and submits again.retry: a known, safe rejection, so the customer can submit again.restore_authorization: your token route failed or the token was rejected; nothing reached OMS, so the customer can submit again without re-entering the card.clear: the fields can’t be reused, so offer the clear button.clear_failed: clearing failed and the billing details were kept. - You act.
check_outcome: the card may or may not have been saved, for example after a timeout, and the form blocks further submits. Reconcile before allowing another attempt.reload: the secure fields failed to load, so reload the page. - Done.
accepted: OMS accepted the card. Clear the form to add another.
409 with code externalAccountAlreadyRegistered instead of the card. For check_outcome, list the customer’s external accounts from your server, keep the entries whose type is card, and match the last four digits and expiry:GET /external-accounts has no type filter, so filter the results yourself. The list is paginated: while hasMore is true, pass the page’s nextCursor as startingAfter to read the next page, and check every page before you decide. If the card is there, use it. If not, let the customer try again.Customize the card form
Style and translate the fields
Passappearance to style the secure fields. It accepts fontFamily, fontSize, fieldHeight, color, placeholderColor, background, borderColor, borderRadius, focusColor, and errorColor, each a plain CSS value:
appearance once, when the form mounts. Changing it on a mounted form is a configuration error, so decide the values before rendering. Labels, billing inputs, buttons, and status text are regular DOM that you style with your own CSS.
Pass messages to replace the default English text. Keys are message IDs, and any key you leave out keeps its default. debitCardMessages from @polygonlabs/oms-card holds every ID with its default text:
DebitCard and the custom element’s configure() take the same appearance and messages options.
Build your own layout
RenderDebitCard with the form’s parts when you own the layout. Like the complete form, it takes everything from OMSProvider. useDebitCard() gives you the submit and clear commands and whether the form can submit:
submit() resolves to accepted, needs_attention, or unconfirmed instead of throwing for expected outcomes. For finer control, replace CardFields with individual CardField elements of type number, expiry, and cvc, and bind your own billing inputs with useDebitCardBillingField(field). Pass defaultBillingAddress to prefill billing.
Use the form without React
The root entry point registers the<oms-debit-card> and <oms-debit-card-field> custom elements. Mount the three secure fields:
OMS object:
getCustomerToken calls your token route, as in the React example. Your page supplies the billing inputs: bind each one with card.registerBillingInput(field, input), or set values with card.setBillingField(field, value). Call card.submit() from your own submit handler and card.subscribe(listener) to observe state. Render from the state alone: state.billing.values holds the current billing input, state.billing.errors the errors to show now, and state.status the status line described in the Handle the result step of Register a card.
Content Security Policy
If your site sets a Content Security Policy, start with these sources for your environment, and add your own customer token route toconnect-src. Allow both sets only if your deployment uses both.
Wait for the card to activate
A new card usually startspending. If the billing country or the customer’s country is prohibited, registration still returns 201, but the card is already rejected with failure.code set to countryProhibited. Wait for active before quoting: subscribe to externalAccount.statusChanged or poll GET /external-accounts/{id}. If it lands in failed or rejected, read failure.code and see Statuses.
Use a card on a quote
Once the card isactive, reference it as the quote source for a buy or the destination for a sell. The card side always uses asset: usd, and OMS infers the network.
amount on one side only. OMS calculates the other.
Execute the transaction
Card transactions are screened for fraud with signals from the customer’s browser. The browser collects a fresh risk session and hands it to your server, and your server creates the transaction. In the browser, callconfirmCardTransaction from @polygonlabs/oms-card with the OMS object you created with risk. It collects the risk session and calls your submit callback once with { quoteId, riskSession }:
unknown, not as a rejection. If risk collection fails or isn’t ready within 30 seconds, confirmCardTransaction resolves to { status: 'risk_unavailable' } and nothing is sent.
On your server, authenticate the user, then create the transaction with POST /transactions, passing the two riskSession values as top-level fields. Take the customer from your authenticated session, never from the request body.
confirm checks that the quote belongs to the customer, sends a stable idempotency key derived from the quote, and returns the result your submit callback should return. If you call the REST endpoint yourself, derive the Idempotency-Key from the quote ID too, and return one of these from submit:
{ status: 'submitted', transactionId }when OMS created the transaction. Submitted is not settled.{ status: 'rejected' }when you know nothing was submitted.{ status: 'unknown' }when the outcome is uncertain. Reconcile on your server before trying again.
webSessionId returns 422 RiskSessionRequired. The quote already identifies the card, so the transaction doesn’t take a card ID.
Let the SDK run the whole journey
In React,useCardTransaction({ transport, draft, enabled }) from @polygonlabs/oms-card/react runs the quote, review, and confirm journey for you. It checks that each quote belongs to the customer, tracks quote expiry, blocks duplicate confirmation, and looks up uncertain outcomes. Your transport has three methods that map one to one to createQuote, retrieve, and confirm from createCardTransactions in @polygonlabs/oms-api, so you can forward their results unchanged. cardQuoteDraft() builds the draft from a saved card, an amount, and a wallet. Without React, createCardTransaction(oms, { transport, draft }) from @polygonlabs/oms-card returns the same controller.
See Transactions for statuses and webhooks.
Test in sandbox and on localhost
Build and test against sandbox. Moving to production is a key swap, not a code change.
Use one of these test cards with any future expiry and any three-digit security code:
- Mastercard Debit
- Visa Prepaid
- Visa Debit
- Add your dev server’s origin, such as
http://localhost:5173, to your sandbox publishable key. - Serve the page from that origin. Opening the HTML as a file (
file://) won’t work. - Run your customer token route locally with your sandbox secret key. Keep the secret in an environment file, not in page code.
- Open the page, type a test card into the secure fields, and submit.
- Poll
GET /external-accounts/{id}until the card isactive.
- The secure host only accepts submissions from the SDK’s secure fields. A
curlor server-side request to it is rejected. - The secure fields are iframes from another origin. Your page script can’t read or set their values, and some browser automation tools can’t type into them. End-to-end tests need a tool that can target cross-origin frames.
- Set
autoComplete="off"on test forms so the browser doesn’t fill in a saved real card. - For component tests, import
createTestCardRiskClient()andcreateVaultTestSession()from@polygonlabs/oms-card/testing. Pass the risk client as theriskoption ofcreateOMSand the session as the form’ssessionprop. Both run in memory with no network calls.
Idempotency
The SDK sets theIdempotency-Key for card registration from the customer token, so you never set one in the browser. Quote and transaction requests from your server need their own key. See Idempotency for how OMS matches keys and the errors it returns.
Related
- Debit cards: the card object, statuses, billing address rules, errors, and events
- External accounts: the shared model for cards, banks, and external wallets
- Transactions: the quote-and-execute flow
- Sandbox and testing: how the sandbox environment behaves
- Receiving webhooks: verify and apply
externalAccount.statusChangedevents