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 on the Finbility-hosted checkout page, which uses the Evervault JS SDK to render the wallet UI and encrypt payment data in the browser.
• 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

Example: INIT (register token with FINBI_3D)

{
  "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",
  "token_id": "INIT",
  "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": ""
  }
}

Example: MIT (FINBI_TN with token)

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

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 pay_url points to a Finbility-hosted checkout page that uses the Evervault JS SDK to render the Apple Pay or Google Pay button and encrypt payment data in the browser — the same security model as finbility-card.js for card payments. The customer authorizes payment in the native 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.

Checkout page security

The wallet checkout page loads the Evervault browser SDK (js.evervault.com/v2) and uses evervault.ui.applePay() or evervault.ui.googlePay() to mount the wallet button. When the customer authorizes payment:

1. The Evervault SDK captures the encrypted payment token from Apple Pay or Google Pay.
2. The encrypted payload is submitted via fetch to a Finbility backend endpoint for processing.
3. The backend decrypts the payload through Evervault Relay and forwards it to the upstream payment provider.
4. The result is returned to the checkout page: success, 3DS challenge, or failure.

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 lands on the Finbility-hosted checkout page, which loads the Evervault SDK and renders the wallet button.
5. The customer taps the Apple Pay or Google Pay button and authorizes payment in the native wallet UI.
6. The Evervault SDK encrypts the payment token and submits it to Finbility for processing.
7. If 3D Secure is required, the customer completes the 3DS challenge; otherwise the payment is finalized.
8. 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"
  }
}

Response after create payment

When the payment is created successfully and a wallet step is required, the response includes pay_url with status RedirectApple or RedirectGoogle. Redirect the customer to pay_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": "RedirectApple",
  "pay_url": "https://payment.finbility.io/payments/65df5a6791a211e583461c6f65f84b6d/checkout",
  "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://...",
  "token_id": "80780000"
}

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"
}

Notify URL response

Return HTTP status 200 on receipt. No response body is required.

Notification retry schedule

If the notification fails or a 200 is not returned, the platform retries at the following intervals: 2 min, 10 min, 10 min, 60 min, 120 min (5 retries total).

Notification signature verification

Notifications do not require signature verification. The recommended approach is to call the query API (GET /v1/payment/{payment_id}) after receiving a notification to confirm the final status. The query API requires OAuth 2.0 authentication. This is recommended because notifications may be delayed or lost.

Refund by order id

Refund request body

{
  "amount": "1.00",
  "currency": "USD",
  "refund_order_id": "R20260414001",
  "notify_url": "https://merchant.example/notify",
  "description": "Customer requested refund"
}

Refund response

{
  "refund_id": "2c04080b91a211e583461c6f65f84b6d",
  "create_time": "2015-07-07T09:10:52Z",
  "update_time": "2015-07-07T09:10:52Z",
  "amount": "1.00",
  "currency": "CNY",
  "order_id": "db9e9e6b-918e-11e5-8346-1c6f65f84b6d",
  "refund_order_id": "e8578eb-91a0-11e5-8346-1c6f65f84b6d",
  "links": [
    {
      "href": "http://.xxx.com/v1/refund/2c04080b91a211e583461c6f65f84b6d",
      "rel": "self",
      "method": "GET"
    }
  ],
  "status": "WAIT",
  "notify_url": "http://www.mysite.com/refund_notify_url"
}

Refund query

Query a refund by its platform refund ID. The response uses the same structure as the refund response above.

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