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.
• Apple Pay and Google Pay use the /v1/paymentCollect API only; redirect the customer to pay_url to complete payment in the wallet.
• Default selectors, hidden field mappings, and built-in copy keep checkout integration minimal.

Prerequisites

• Client ID and Client Secret for Finbility OAuth.
• A checkout page served over HTTPS.

Base URL

Get your Client ID and Client Secret

API credentials are managed in the merchant dashboard under Settings > My profile > API Key.

• Use the displayed Client ID together with the Client Secret returned when the key is first generated or reset.
• The dashboard only shows a masked secret after creation. Save the full Client Secret immediately because it is only displayed once.
• If the secret is lost or needs to be rotated, reset the API Key in the dashboard and update your backend configuration before requesting new OAuth tokens.

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 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. Initialize FinbilityPayCard. The secure component renders cardholder name, card number, expiry, and CVC.
4. Submit the form only after controller.hasEncryptedPayload() is true.

Environment script URLs

Use the matching script URL for each environment.

<script src="https://test.payment.finbility.io/web/js/finbility-card.js"></script>

<form id="credit_card_form" action="<YOUR_BACKEND_PAYMENT_ENDPOINT>" 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({
    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>

Configuration and customization

Hidden inputs can be pre-rendered by the merchant form or created automatically by the component. Locale, theme, callbacks, and selectors can be customized without changing the integration model.

window.FinbilityPayCard.create({
  locale: "en_US"
});

Example with custom selectors and hidden field ids

window.FinbilityPayCard.create({
  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.

Card payment: send the encrypted payload to the payment API

Your backend receives the form submission, maps the encrypted values to Finbility request fields, and calls /v1/paymentDirect with your OAuth access token. Wallet payments (Apple Pay, Google Pay) use /v1/paymentCollect instead.

Request headers

Core request fields

Customer source fields

{
  "return_url": "https://merchant.example/return",
  "notify_url": "https://merchant.example/notify",
  "payment_method": "FINBI_3D",
  "request_type": "WEB",
  "order_id": "100096247512",
  "amount": "1.00",
  "currency": "USD",
  "description": "Product Title",
  "website": "https://merchant.example",
  "cardnum": "ev:encrypted:card-number",
  "cardmonth": "09",
  "cardyear": "2026",
  "cardcvv": "ev:encrypted:cvc",
  "cardholder": "Chris Ma",
  "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"}

Apple Pay and Google Pay

Apple Pay and Google Pay are server-side collect flows. Your backend calls /v1/paymentCollect with the wallet payment method code, then redirects the customer to the pay_url returned in the API response. The customer completes payment in the Apple Pay or Google Pay wallet UI; Finbility notifies your notify_url and redirects to return_url when finished.

These methods do not use finbility-card.js and do not accept card fields. Request parameters match the card payment API except for the endpoint, payment_method, and the absence of card-related fields.

Payment method codes

Integration flow

1. Obtain an OAuth access token (same as other backend APIs).
2. POST order and customer details to /v1/paymentCollect with FINBI_AP or FINBI_GP.
3. Read pay_url from the response and redirect the customer (HTTP 302 or client-side window.location).
4. The customer authorizes payment in Apple Pay or Google Pay.
5. Receive the final result on notify_url and reconcile with GET /v1/payment/{payment_id} if needed.

Request headers

Core request fields

Same fields as the card payment API, except card fields and the 3DS BrowserInfo header are not used.

Example: Apple Pay

{
  "return_url": "https://merchant.example/return",
  "notify_url": "https://merchant.example/notify",
  "payment_method": "FINBI_AP",
  "request_type": "WEB",
  "order_id": "100096247513",
  "amount": "1.00",
  "currency": "USD",
  "description": "Product Title",
  "website": "https://merchant.example",
  "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"
  }
}

Example: Google Pay

{
  "return_url": "https://merchant.example/return",
  "notify_url": "https://merchant.example/notify",
  "payment_method": "FINBI_GP",
  "request_type": "WEB",
  "order_id": "100096247514",
  "amount": "1.00",
  "currency": "EUR",
  "description": "Product Title",
  "website": "https://merchant.example",
  "source": {
    "first_name": "Chris",
    "last_name": "Ma",
    "country": "DE",
    "city": "Berlin",
    "zip": "10115",
    "email": "test@example.com",
    "phone": "+49-30-1234567",
    "address1": "Example Street 1",
    "client_ip": "203.0.113.10"
  }
}

Redirect after create payment

When the payment is created successfully and a wallet step is required, the response includes pay_url. Redirect the customer to that URL to enter the Apple Pay or Google Pay flow. Query and webhook behavior are the same as for card payments.

{
  "payment_id": "65df5a6791a211e583461c6f65f84b6d",
  "transaction_id": "72c17f2d91a211e583461c6f65f84b6d",
  "payment_method": "FINBI_AP",
  "status": "PENDING",
  "pay_url": "https://...",
  "order_id": "100096247513",
  "amount": "1.00",
  "currency": "USD"
}

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": "FINBI",
  "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": "FINBI_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.

Test cards

Use the following values in the test environment (https://test.openapi.finbility.io). Do not use them in production.

Pure API integration (encrypted payloads)

For backend-only testing with POST /v1/paymentDirect, send the pre-encrypted sandbox values below. Map them to cardnum and cardcvv; set cardmonth to 12 and cardyear to 2027.

Checkout UI integration (plain text)

For testing with finbility-card.js on the hosted checkout page or the demo page, enter these values in the secure card form. The component encrypts card number and CVC before submit.

Status and error handling