Accept card payments with one frontend script and a standard backend API.

Integration model

Finbility provides a standard REST payment API plus a merchant-side secure card component. The frontend component is delivered through finbility-card.js, which wraps Evervault card fields behind a simpler integration surface.

• Frontend renders one secure card block and writes encrypted values into your form.
• Backend uses OAuth 2.0, then calls payment, query, webhook, and refund APIs.
• Default selectors, hidden field mappings, and built-in copy keep checkout integration minimal.

Prerequisites

• Client ID and Client Secret for Finbility OAuth.
• A backend service that generates the checkout token for the page.
• A checkout page served over HTTPS.

Base URL

Get an access token before calling backend APIs

{
  "access_token": "653633b2-8287-47b6-a7e4-40ec252fe9a8",
  "token_type": "bearer",
  "expires_in": 43035,
  "scope": "write,read"
}

Use finbility-card.js as the merchant integration layer

The script automatically loads the Evervault browser SDK, generates the secure card UI inside your mount element, manages loading and error states, enables the submit button when the encrypted payload is ready, and writes values into hidden inputs.

• The component handles secure fields, default copy, loading state, and hidden field updates.
• You control token delivery, locale, theme, callbacks, form action, and backend payload mapping.
• The default integration only needs one script tag, one mount div, and one submit button.

Minimal integration

1. Include finbility-card.js on the checkout page.
2. Add a form with a single mount container and a submit button.
3. Pass a backend-generated token. The secure component renders cardholder name, card number, expiry, and CVC.
4. Submit the form only after controller.hasEncryptedPayload() is true.

<script src="/web/js/finbility-card.js"></script>

<form id="credit_card_form" action="/standard/credit_card" method="post" novalidate>
  <div id="finbility-pay-card"></div>

  <input type="hidden" name="cardholderName" id="finbility-pay-holder">
  <input type="hidden" name="cardNumber" id="finbility-pay-card-number">
  <input type="hidden" name="expirationMonth" id="finbility-pay-expiration-month">
  <input type="hidden" name="expirationYear" id="finbility-pay-expiration-year">
  <input type="hidden" name="cvNumber" id="finbility-pay-cv-number">

  <button type="submit" id="js-pay-btn" disabled="disabled">Pay</button>
</form>

<script>
  var controller = window.FinbilityPayCard.create({
    token: "BASE64_TOKEN_FROM_BACKEND",
    locale: "en_US"
  });

  document.getElementById("credit_card_form").addEventListener("submit", function (event) {
    event.preventDefault();

    if (!controller || controller.isFailed()) {
      return;
    }

    if (!controller.hasEncryptedPayload()) {
      return;
    }

    this.submit();
  });
</script>

Token, hidden fields, and customization

The public integration entry point is token. Hidden inputs can be pre-rendered by the merchant form or created automatically by the component, and the rest of the checkout behavior can be customized through selectors, messages, theme, and callbacks.

{
  "token": "BASE64_TOKEN_FROM_BACKEND"
}

Example with custom selectors and hidden field ids

window.FinbilityPayCard.create({
  token: "BASE64_TOKEN_FROM_BACKEND",
  locale: "zh_CN",
  selectors: {
    mount: "#custom-pay-card",
    form: "#custom-form",
    submitButton: "#submit-btn"
  },
  hiddenFields: {
    holder: { id: "encryptedHolder", name: "cardholderName" },
    number: { id: "encryptedCardNumber", name: "cardNumber" },
    expiryMonth: { id: "encryptedMonth", name: "expirationMonth" },
    expiryYear: { id: "encryptedYear", name: "expirationYear" },
    cvc: { id: "encryptedCvc", name: "cvNumber" }
  }
});

Browser expectations

• finbility-card.js is implemented in ES5 style for broad browser compatibility.
• Target current versions of Chrome, Edge, Safari, and Firefox for merchant checkout pages.
• The script loads the Evervault browser SDK internally, so merchants only need to include one JS file.

Send the encrypted payload to the payment API

Your backend receives the form submission, maps the encrypted values to Finbility request fields, and calls the payment endpoint with your OAuth access token.

Request headers

Core request fields

Customer source fields

{
  "return_url": "https://merchant.example/return",
  "notify_url": "https://merchant.example/notify",
  "payment_method": "EECPB_3D",
  "request_type": "WEB",
  "order_id": "100096247512",
  "amount": "1.00",
  "currency": "USD",
  "description": "Product Title",
  "website": "https://merchant.example",
  "cardnum": "ev:encrypted:card-number",
  "cardexpiry": "0926",
  "cardcvv": "ev:encrypted:cvc",
  "source": {
    "first_name": "Chris",
    "middle_name": "",
    "last_name": "Ma",
    "country": "US",
    "state": "CA",
    "city": "Los Angeles",
    "zip": "90001",
    "email": "test@example.com",
    "phone": "1-555-0100",
    "address1": "100 Main Street",
    "address2": "Suite 18",
    "client_ip": "203.0.113.10",
    "cpf": ""
  }
}

3DS browser header

BrowserInfo: {"acceptHeader":"application/json","language":"en","userAgent":"Mozilla/5.0","javaEnabled":"true","colorDepth":"24","screenHeight":"1080","screenWidth":"1920","timeZoneOffset":"-480"}

Response and query flow

The create-payment response and the payment query response share the same core structure.

{
  "payment_id": "65df5a6791a211e583461c6f65f84b6d",
  "transaction_id": "72c17f2d91a211e583461c6f65f84b6d",
  "create_time": "2015-07-07T08:05:38Z",
  "update_time": "2015-07-07T08:05:38Z",
  "payment_method": "EECPB_3D",
  "status": "SUCCESS",
  "error_code": "",
  "remarks": "",
  "order_id": "100096247512",
  "description": "Product Title",
  "amount": "1.00",
  "currency": "USD",
  "request_type": "WEB",
  "pay_url": "https://..."
}

Payment result notification

Finbility sends a POST request to your notify_url when the payment result is available.

{
  "transaction_id": "72c17f2d91a211e583461c6f65f84b6d",
  "order_id": "100096247512",
  "payment_id": "65df5a6791a211e583461c6f65f84b6d",
  "payment_method": "EECPB_3D",
  "error_message": "",
  "status": "SUCCESS"
}

Refund by order id

Refund request body

{
  "amount": "1.00",
  "currency": "USD",
  "refund_order_id": "R20260414001",
  "description": "Customer requested refund"
}

Refund query

The response returns the refund identifier, status, amount, currency, timestamps, and any failure reason.

Status and error handling