AuxCORE SDK#

The AuxCORE SDK (auxVault.js) puts a card or bank-account checkout on your own website without bringing card data into your PCI scope. It shows the customer the exact total including any technology fee, charges card or ACH, and reports the result — your server then learns the final outcome from webhooks.

How it fits together:

• auxVault.js and the card fields are served from the AuxCORE vault (vault.auxcore.net). The card number is typed into a vault iframe and turned into a pci_tok_… token there; your page never sees it.
• Quotes and payments go to the AuxCORE API for your environment (uat.auxcore.net for Sandbox, app.auxcore.net for Production).
• Bank-account (ACH) details are not card data: they are read from their fields and sent with the payment.

Before you start#

1. In the dashboard open Settings → Developer & Integrations → API Keys and create a Website checkout (No-Code SDK) key (lpk_live_…).
2. List every site that will host the checkout under Allowed origins, for example https://shop.example.com. The SDK refuses to load on any other origin.
3. Check which payment methods your account takes: card, ACH, or both. The SDK only offers a method that has an active gateway.

Quick start: card and ACH checkout, no code#

Paste this into your checkout page. With data-auto-init="true" the SDK mounts the fields, offers card or bank account, keeps the subtotal, fee and total up to date, and wires the pay button.

<!-- Card or bank account. Hidden automatically when your account takes only one. -->
<select data-auxvault-method-switch>
  <option value="card">Card</option>
  <option value="ach">Bank account</option>
</select>

<div data-auxvault-method="card">
  <div data-auxvault="card"></div>
</div>
<div data-auxvault-method="ach">
  <div data-auxvault="routingNumber"></div>
  <div data-auxvault="accountNumber"></div>
</div>

<div data-auxvault="name"></div>
<div data-auxvault="email"></div>
<div data-auxvault="amount"></div>

<p>Subtotal <span data-auxvault-subtotal></span> · Fee <span data-auxvault-fee></span></p>
<button data-auxvault-button="pay">Pay <span data-auxvault-total></span></button>
<div data-auxvault-result></div>

<script src="https://vault.auxcore.net/sdk/auxVault.js"
        data-auto-init="true"
        data-api-key="lpk_live_YOUR_KEY"
        data-endpoint="https://uat.auxcore.net/api/v1/public"
        data-default-amount="25.00">
</script>

• Always show data-auxvault-total: when your account charges a technology fee, the customer pays more than the amount they typed, and this is the figure they are charged.
• An ACH payment needs a name: keep the name field, or add accountHolderName when the account holder is not the person paying.
• ACH payments come back pending, not paid. See Results.

Fees and who pays#

The technology fee is set on your AuxCORE account; the SDK never computes it. quote() and the payment use the same pricing, so the total you show is the total charged.

• Card and ACH can be priced differently, for example 3.75% with no cap on card and 1% capped at $100 on ACH.
• A fee is the rate × amount, raised to the account's minimum and held at its maximum when it has one.

Choosing who pays the fee#

Send convenienceFeeActive with the payment, and the same value with the quote. When your account allows choosing who pays:

• Who pays by default, and whether you may choose per payment, are settings on your AuxCORE account. Ask AuxCORE support which apply to yours.
• When your account does not allow changing who pays, the value you send is ignored and the fee follows your account. The quote and the payment response then carry the warning payer_change_not_allowed.
• The no-code checkout always uses the default payer. To choose per payment, use the JavaScript API.
• The payment response reports what was applied in ConvenienceFee and ConvenienceFeeActive. quote() returns a warning ({ code, message }) when a fee you asked for came back as zero, or when your choice of payer was not applied.

Results#

The no-code checkout writes the outcome into data-auxvault-result and, with data-success-url, redirects after a successful payment. With the JavaScript API, createTransaction() resolves on success and throws an Error with the decline reason otherwise.

response.data carries TransactionId, Status, Amount (fee included), BaseAmount, ConvenienceFee and ConvenienceFeeActive. response.warnings appears when the fee was not applied as requested (for example payer_change_not_allowed). Fields are cleared after a successful payment.

The amount on a browser checkout comes from the page — the amount field, data-default-amount, data-amount or ?amount= in the URL — so the customer can change it. Before you fulfil an order, check baseAmount in the webhook against the order on your server.

Webhooks for SDK payments#

Register an endpoint under Settings → Developer & Integrations → Webhooks and subscribe to:

Verify the X-Webhook-Signature header on every delivery. Payloads and signing: Webhook events.

JavaScript API#

Use it to build your own form, choose who pays per payment, or show the fee before the customer commits.

<div id="card"></div>
<div id="routing"></div>
<div id="account"></div>
<p id="total"></p>
<button id="pay">Pay</button>

<script src="https://vault.auxcore.net/sdk/auxVault.js"></script>
<script type="module">
  const sdk = AuxVault('lpk_live_YOUR_KEY', {
    endpoint: 'https://uat.auxcore.net/api/v1/public/transaction', // the …/transaction URL
  });

  const card = sdk.createElement('card');
  card.mount('#card');
  const methods = await sdk.paymentMethods(); // { card: true, ach: true, available: ['card', 'ach'], … }
  if (methods.ach) {
    sdk.createElement('routingNumber').mount('#routing');
    sdk.createElement('accountNumber').mount('#account');
  }

  const amount = 100;
  const method = 'card';                       // or 'ach'
  const payer = { convenienceFeeActive: true }; // omit for the account default

  const q = await sdk.quote(amount, { paymentMethod: method, ...payer });
  document.getElementById('total').textContent =
    `${q.baseAmount} + ${q.convenienceFee} fee = ${q.totalAmount}`;

  document.getElementById('pay').addEventListener('click', async () => {
    try {
      const res = await sdk.createTransaction({
        amount, paymentMethod: method, ...payer,
        billingName: 'Jane Doe', billingEmail: 'jane@example.com',
      });
      console.log(res.pending ? 'ACH submitted' : 'Paid', res.response.data.TransactionId);
    } catch (err) {
      console.error(err.message); // decline reason or a configuration problem
    }
  });
</script>

createTransaction() also takes billingName, billingEmail, billingPhone, billingAddress, billingCity, billingState, billingPostal, accountType (checking or savings), and accountNumber / routingNumber when you do not mount those fields. A mounted field's value wins over the same parameter. Routing numbers must be 9 digits.

Script attributes#

Payments from the script tag are sales, captured immediately.

Fields and markers#

Add data-auxvault="…" to empty elements:

There is no country field, and the postal field is postal, not zip. An unknown data-auxvault value renders nothing.

Field Config — showing and requiring fields#

Which of the customer fields a checkout shows, and which it requires, is set under Settings → Payments → Field Rules, SDK / Embedded Checkout column. The no-code checkout applies it for you:

• a field turned off is hidden;
• a required field is flagged, and the pay button refuses to charge until it is filled.

Four fields are configurable: Full name, Email, Phone, Billing Address. The rest of the catalog is N/A on this channel. Mark each label and field as one unit so a hidden field takes its label with it:

<div data-auxvault-field-group>
  <label>Phone</label>
  <div data-auxvault="phone"></div>
</div>

• Requiring a field you never mounted blocks every payment. The SDK names the element to add in the browser console as soon as the page loads.
• Your gateway can add requirements of its own (a TSYS account requires a billing address); the result already includes them.

For your own form, read it with fieldConfig() or over REST:

{
  "success": true,
  "data": {
    "channel": "sdk",
    "fields": {
      "Email": { "display": true, "required": true },
      "Phone": { "display": false, "required": false },
      "PO": { "na": true }
    },
    "requireCvv": true
  }
}

fields: null means the configuration could not be resolved; render your form as written. The endpoint takes an SDK key, shares the 30 requests / 15 minutes per IP limit of the token endpoints, and needs X-Merchant-ID with a tenant-scoped key.

Tokenize only (charge from your server)#

When your server must set the amount or run its own checks first, collect the card with the SDK and charge the token from your server.

<div id="card-element"></div>
<button id="pay">Pay</button>

<script src="https://vault.auxcore.net/sdk/auxVault.js"></script>
<script>
  const auxvault = AuxVault('lpk_live_YOUR_KEY', {
    endpoint: 'https://uat.auxcore.net/api/v1/public/transaction',
  });
  const card = auxvault.createElement('card');
  card.mount('#card-element');

  document.getElementById('pay').addEventListener('click', async () => {
    const pciToken = await card.tokenize(); // "pci_tok_…"
    await fetch('/checkout', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ pciToken }),
    });
  });
</script>

• Your server charges it with its secret key: POST /api/v1/public/transaction with pciToken (see Quick Start, step 3b).
• Amount is the amount before the fee. When your account charges a technology fee it is added on top, so quote first with GET /api/v1/public/fee-preview and show the customer totalAmount.
• tokenize() rejects with an Error when tokenization fails or does not answer within 15 seconds. Show the message and let the customer retry.
• The key's Allowed origins still apply to the page.

Security#

• The SDK key (lpk_live_…) is public and belongs in your HTML. It can only run the browser checkout: it cannot tokenize raw cards through /tokenize-card, charge saved bank accounts, or be used by plugins.
• A secret key (api-…) must never appear in browser code.
• Card numbers and CVVs stay inside the vault iframes; they never reach your page or your server.
• With Allowed origins set (required when you create the key), requests without an Origin / X-Merchant-Origin header — curl, for example — are refused with 403.
• Anything the browser sends, including the amount, can be changed by the customer. Confirm the amount from the webhook before you fulfil.

Testing#

1. Use a Sandbox key with data-endpoint on uat.auxcore.net.
2. Try the checkout in Settings → Developer & Integrations → SDK & API Docs (/settings/developer/sdk) before adding it to your site.
3. Card: any card from the test card list. ACH: routing number 021000021 with a test account number; the payment stays pending until it settles.
4. Confirm each webhook in the table above reaches your endpoint, including transaction.voided and transaction.refunded from voiding and refunding a test payment in the dashboard.

Troubleshooting#

Server-side alternatives#

For ERP and server-to-server integrations, call POST /api/v1/public/transaction with a secret key instead of using the SDK — see Quick Start. The /api/v1/auxvault/* namespace and its contracts are described under AuxCORE SDK contracts; it does not accept SDK keys.

Next steps#

• Webhooks → — receive payment outcomes
• Fee preview → — quote from your server
• Testing → — test cards and the QA checklist

Need help? Contact support@auxcore.net