Accept and pay out to debit cards

​

Before you start

• 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 with structured names. Cards are registered under the customer’s firstName and lastName. A customer that is not an individual is 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 browser SDK. The SDK packages are in early access and are not available from the public npm registry. Contact us to request access.

​

Get a publishable key

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.

​

Register a card

​

1. Install the packages

npm install @polygonlabs/oms-sdk @polygonlabs/oms-risk-sdk

​

2. Add a customer token route to your server

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.

curl -X POST https://sandbox-api.polygon.technology/v0.13/customers/{customerId}/token \
  -H "Authorization: Bearer {accessToken}"
# → { "token": "…", "expiresAt": "…" }

​

3. Create the OMS client and render the form

import { createRiskClient } from '@polygonlabs/oms-risk-sdk'
import { createOMS } from '@polygonlabs/oms-sdk'
import { OMSProvider, DebitCardForm } from '@polygonlabs/oms-sdk/react'

const oms = createOMS({
  publishableKey: 'pk_sdbx_…',
  risk: createRiskClient(),
  async getCustomerToken(customerId) {
    const response = await fetch('/api/oms/customer-token', {
      method: 'POST',
      body: JSON.stringify({ customerId }),
    })
    if (!response.ok) throw new Error('Could not authorize the card submission')
    return response.json()
  },
})

export function AddCard({
  customerId,
  onSaved,
}: {
  customerId: string
  onSaved: (externalAccountId?: string) => void
}) {
  return (
    <OMSProvider oms={oms} customerId={customerId}>
      <DebitCardForm onSuccess={({ externalAccountId }) => onSaved(externalAccountId)} />
    </OMSProvider>
  )
}

​

4. Handle the result

curl "https://sandbox-api.polygon.technology/v0.13/external-accounts?customerId={customerId}" \
  -H "Authorization: Bearer {accessToken}"

​

Content Security Policy

​

Wait for the card to activate

​

Use a card on a quote

{
  "customerId": "cst_…",
  "source": {
    "type": "card",
    "details": { "id": "ext_…", "asset": "usd" },
    "amount": "100.00"
  },
  "destination": {
    "type": "walletExternal",
    "details": { "id": "ext_…", "asset": "usdc", "network": "polygon" }
  }
}

{
  "customerId": "cst_…",
  "source": {
    "type": "walletCrypto",
    "details": { "id": "wlt_…", "asset": "usdc", "network": "polygon" },
    "amount": "100.00"
  },
  "destination": {
    "type": "card",
    "details": { "id": "ext_…", "asset": "usd" }
  }
}

​

Execute the transaction

{
  "quoteId": "qt_…",
  "webSessionId": "…",
  "deviceFingerprint": "…"
}

• { 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.

​

Test in sandbox and on localhost

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 the test card into the secure fields, and submit.
5. Poll GET /external-accounts/{id} until the card is active.

• 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 createTestRiskClient() and createVaultTestSession() from @polygonlabs/oms-sdk/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

• Same key and body, after the first request finished: OMS returns the original response.
• Same key while the first request is still running: 409 with code idempotencyKeyInProgress. Wait, then retry with the same key.
• Same key, different body: 422 with code idempotencyKeyReuse. Use a new key for a corrected request.
• No key: 400 with code missingIdempotencyKey.
• After a timeout: retry with the same key until you get a definite answer.

{ "error": "Idempotency key already used with a different request", "code": "idempotencyKeyReuse" }

​

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.statusChanged events