Skip to main content
This guide registers a customer’s debit card with the OMS browser SDKs, then uses it as the source of a buy and the destination of a sell. For how registration works, the card object, statuses, and errors, see Debit cards.

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, and lastName as shown in Customer onboarding. The card is registered under that name. Other customer types are rejected with 422 AccountTypeRequirementsNotMet.
  • A secret API key and secret (sk_sdbx_… or sk_live_…) for your server. See Get started.
  • A publishable key (pk_sdbx_… or pk_live_…) for the browser. See Get a publishable key.
  • Access to the OMS SDK packages. @polygonlabs/oms-core, @polygonlabs/oms-card, and @polygonlabs/oms-risk are 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.
  1. In the OMS Dashboard, open API Keys.
  2. Create a Publishable key for the environment you’re building in, sandbox or production.
  3. Add the origin of each page that shows the card form.
An origin is a scheme, a host, and an optional port, with no path or trailing slash: 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 { customerId } from the browser. It must:
  1. Authenticate your own signed-in user, with your usual session and CSRF protections.
  2. Refuse the request if customerId isn’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.
  3. Create a token for that customer with your project access token (see Get started) and return the { token, expiresAt } response unchanged.
Use any server language. If your backend uses JavaScript or TypeScript, you can use the optional @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.
Tokens expire after one minute, so create a fresh one for every call. Don’t prefetch or cache them. Token creation takes no 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, and clearing mean work is in progress. blocked means 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.
Don’t retry automatically. Each customer token carries its own idempotency key, so a retry with a fresh token is a new request. If the first attempt saved the card, the retry returns 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

Pass appearance to style the secure fields. It accepts fontFamily, fontSize, fieldHeight, color, placeholderColor, background, borderColor, borderRadius, focusColor, and errorColor, each a plain CSS value:
The secure fields read 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

Render DebitCard 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:
Then identify the customer and configure the element with your 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 to connect-src. Allow both sets only if your deployment uses both.
The fraud-screening collector loads a remote script whose requests are not fully covered by this list. Check its requests in your deployment before you enforce the policy.

Wait for the card to activate

A new card usually starts pending. 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 is active, 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.
Set 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, call confirmCardTransaction 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 }:
A thrown callback or a malformed result counts as 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.
Pass the risk session values through unchanged. Keep them in memory only, and never log or store them. A card transaction without 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:
To run the card form on your own machine:
  1. Add your dev server’s origin, such as http://localhost:5173, to your sandbox publishable key.
  2. Serve the page from that origin. Opening the HTML as a file (file://) won’t work.
  3. Run your customer token route locally with your sandbox secret key. Keep the secret in an environment file, not in page code.
  4. Open the page, type a test card into the secure fields, and submit.
  5. Poll GET /external-accounts/{id} until the card is active.
Keep in mind:
  • The secure host only accepts submissions from the SDK’s secure fields. A curl or 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() and createVaultTestSession() from @polygonlabs/oms-card/testing. Pass the risk client as the risk option of createOMS and the session as the form’s session prop. Both run in memory with no network calls.

Idempotency

The SDK sets the Idempotency-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.