Fluidpay API Documentation

Gateway Information

Both environments require JavaScript enabled:

• Sandbox (testing): https://sandbox.fluidpay.com
• Production (live): https://app.fluidpay.com

Current Version

1.5.1 (fully backwards compatible)

Required Headers

Authorization

Must include one of the following:

Authorization: Bearer { JWTToken }

Authorization: { API Key }

Content-Type

Usually set to application/json

API Keys

• Public keys (pub_***): For client-side requests only (Tokenizer, Cart Sessions)
• Private keys (api_***): For server-side requests only (Transaction Processing)

Error Handling

Uses standard HTTP status codes with JSON error responses:

{
  "status": "failed",
  "msg": "bad request error: invalid Postal Code"
}

Troubleshooting Unauthorized Responses

Check for:

• Missing Authorization header
• Invalid or deleted API key
• Incorrect API key type (public vs private)
• Incorrect account type (Partner vs Merchant)
• Wrong environment (sandbox vs production)

Support

All responses include a correlation ID (x-correlation-id) in the header. Include this ID in support requests.

Process Transaction

Key Request Parameters

Parameter	Type	Description	Required
type	string	"sale", "authorize", "verification" or "credit"	Yes
amount	integer	Amount in cents including all fees (1299 = $12.99)	Yes
base_amount	integer	Base amount in cents before fees (1299 = $12.99)	No
currency	string	ISO 4217 currency (default: "USD")	No
description	string	Transaction notes (max 255 characters)	No
order_id	string	Up to 17 alphanumeric characters	For L3 processing
processor_id	string	Processor to use for transaction	If no default set
payment_method	object	Payment method details (card, ach, customer, terminal, token, apm)	Yes

Payment Methods

Must include one of the following payment methods:

Card Payments

{
  "payment_method": {
    "card": {
      "number": "4111111111111111",
      "expiration_date": "12/25",
      "cvc": "123"
    }
  }
}

ACH Payments

{
  "payment_method": {
    "ach": {
      "routing_number": "123456789",
      "account_number": "123456789",
      "sec_code": "web",
      "account_type": "checking"
    }
  }
}

Customer Vault

{
  "payment_method": {
    "customer": {
      "id": "customer_id",
      "payment_method_id": "payment_method_id"
    }
  }
}

Terminal

{
  "payment_method": {
    "terminal": {
      "id": "terminal_id",
      "print_receipt": "both",
      "signature_required": true
    }
  }
}

Address Information

You can include billing and shipping information:

"billing_address": {
  "first_name": "John",
  "last_name": "Smith",
  "company": "Test Company",
  "address_line_1": "123 Main St",
  "city": "Chicago",
  "state": "IL",
  "postal_code": "60601",
  "country": "US",
  "email": "john@example.com",
  "phone": "5555555555"
}

Transaction Management

Get Transaction

Search Transactions

Capture

Capture funds for a previously authorized transaction.

Void / Auth Reversal

Void a transaction that is pending settlement.

Refund

Process a refund for a settled transaction. Multiple partial refunds allowed up to the settled amount.

Response Codes

Code Range	Description
100-199	Approvals and Partial Approvals
200-299	Declined via processor
300-399	Gateway Declines
400-499	Processor rejection errors

Batch Terminal

Settle individual terminals with a POST request:

Search Settlement Batches

Request Parameters

Parameter	Type	Description	Default	Required
batch_date.start_date	string	Start of date range (UTC "YYYY-MM-DDTHH:II:SSZ")	""	No
batch_date.end_date	string	End of date range (UTC "YYYY-MM-DDTHH:II:SSZ")	""	No
settlement_batch_id.operator	string	"=" or "!="	-	No
settlement_batch_id.value	string	Batch ID to match or exclude	-	No
limit	integer	Number of results to return (1-100)	10	No
offset	integer	Number of results to skip (1-1000)	0	No

Overview

Batch upload allows you to process multiple transactions by uploading a CSV file. Files are validated and queued for processing. Once completed, a batch can be downloaded in CSV format with transaction results.

CSV Format Requirements

• First row must be a header with field names
• Each field should be wrapped in quotes without nested quotes
• Fields must be separated by commas
• Each row must end with a newline character

"transaction_type","amount","cc_number","cc_expiration"
"sale","100","4111111111111111","12/25"

Required Fields

Field	Required	Description
transaction_type	Yes	sale, authorize, or credit
amount	Yes	Amount as integer ($1.00 = 100)
cc_number	For card payments	Credit card number
cc_expiration	For card payments	Card expiration date (MM/YY)
ach_account_number	For ACH payments	ACH account number
ach_routing_number	For ACH payments	ACH routing number
ach_account_type	For ACH payments	"checking" or "savings"
ach_sec_code	For ACH payments	WEB, CCD, or PPD
customer_id	For customer vault	Customer vault ID to charge

API Endpoints

Upload Batch File

curl -H "Authorization: APIKEY" -F "file=@filename.csv" "https://app.fluidpay.com/api/filebatch"

// Response
{
  "status": "success",
  "data": {
    "id": "bj1o70m9ku6fr2s21fig",
    "file_name": "filename.csv",
    "status": "pending",
    "num_lines": 1,
    "created_at": "2023-04-26T22:17:38.078185Z"
  }
}

Check Batch Status

curl -H "Authorization: APIKEY" "https://app.fluidpay.com/api/filebatch/{batch_id}"

// Response
{
  "id": "bj1o70m9ku6fr2s21fig",
  "file_name": "filename.csv",
  "status": "completed", // pending, queued, processing, failed, or completed
  "num_lines": 1,
  "processed_lines": 1,
  "created_at": "2023-04-26T22:17:38Z",
  "updated_at": "2023-04-26T22:18:10Z"
}

Download Results

Add-Ons

Add-ons adjust recurring charge amounts by either a set amount or percentage.

Create Add-On

Parameter	Type	Description	Required
name	string	Display name	No
description	string	Description	No
amount	integer	Amount in cents (100 = $1.00)	*
percentage	integer	Percentage (43440 = 43.440%)	*
duration	integer	Billing cycles (0 = until cancelled)	No

Other Add-On Operations

• GET /api/recurring/addon/{id} - Get add-on details
• GET /api/recurring/addons - List all add-ons
• POST /api/recurring/addon/{id} - Update add-on
• DELETE /api/recurring/addon/{id} - Delete add-on

Discounts

Discounts reduce recurring charge amounts by either a set amount or percentage.

Create Discount

Parameter	Type	Description	Required
name	string	Display name	No
description	string	Description	No
amount	integer	Amount in cents (100 = $1.00)	*
percentage	integer	Percentage (43440 = 43.440%)	*
duration	integer	Billing cycles (0 = until cancelled)	No

Other Discount Operations

• GET /api/recurring/discount/{id} - Get discount details
• GET /api/recurring/discounts - List all discounts
• POST /api/recurring/discount/{id} - Update discount
• DELETE /api/recurring/discount/{id} - Delete discount

Plans

Plans define recurring billing schedules with optional add-ons and discounts.

Create Plan

Parameter	Type	Description	Required
name	string	Display name	Yes
description	string	Description	No
amount	integer	Amount in cents (100 = $1.00)	Yes
billing_cycle_interval	integer	Run every X months	Yes
billing_frequency	string	"monthly", "twice_monthly", or "daily"	Yes
billing_days	string	Day(s) to bill on, comma-separated (e.g., "1,15"); "0" for last day of month	Yes
duration	integer	Billing cycles (0 = until cancelled)	No
add_ons	array	Array of add-on objects with IDs and optional overrides	No
discounts	array	Array of discount objects with IDs and optional overrides	No

Other Plan Operations

• GET /api/recurring/plan/{id} - Get plan details
• GET /api/recurring/plans - List all plans
• POST /api/recurring/plan/{id} - Update plan
• DELETE /api/recurring/plan/{id} - Delete plan

Subscriptions

Subscriptions apply plans to customers for recurring billing.

Create Subscription

Parameter	Type	Description	Required
plan_id	string	ID of the plan	Yes
customer.id	string	Customer ID	Yes
customer.payment_method_type	string	"card" or "ach"	No
customer.payment_method_id	string	ID of payment method	If type provided
amount	integer	Amount in cents	Yes
next_bill_date	string	Next billing date (YYYY-MM-DD)	No

Subscription Status Management

• GET /api/recurring/subscription/{id}/status/paused - Pause subscription
• GET /api/recurring/subscription/{id}/status/past_due - Mark as past due
• GET /api/recurring/subscription/{id}/status/cancelled - Cancel subscription
• GET /api/recurring/subscription/{id}/status/active - Activate subscription
• GET /api/recurring/subscription/{id}/status/completed - Complete subscription

Other Subscription Operations

• GET /api/recurring/subscription/{id} - Get subscription details
• POST /api/recurring/subscription/{id} - Update subscription
• DELETE /api/recurring/subscription/{id} - Delete subscription

Transaction requests should be processed through the /transaction endpoint, referencing the specific terminal to handle the request.

Get All Terminals

Response Structure

{
  "status": "success",
  "msg": "",
  "total_count": 1,
  "data": [
    {
      "id": "1ucio551tlv85l7moe5s",
      "merchant_id": "aucio551tlv85l7moe5g",
      "manufacturer": "dejavoo",
      "model": "z11",
      "serial_number": "1811000XXXX",
      "tpn": "1811000XXXX",
      "description": "front counter z11",
      "status": "active",
      "auth_key": "wcR1c9o1",
      "register_id": "1",
      "auto_settle": true,
      "settle_at": "00:00:00",
      "created_at": "2018-01-12T03:57:59Z",
      "updated_at": "0001-01-01T00:00:00Z"
    }
  ]
}

Field	Description
id	Terminal identifier
merchant_id	Associated merchant identifier
manufacturer	Terminal manufacturer (e.g., "dejavoo")
model	Terminal model (e.g., "z11")
status	Terminal status (e.g., "active")
auto_settle	Whether the terminal automatically settles transactions
settle_at	Time when automatic settlement occurs

Create Invoice

Key Parameters

Parameter	Description	Required
currency	Currency code (e.g., "USD")	Yes
payable_to	Object with merchant details	Yes
bill_to	Object with customer billing details	Yes
date_due	Due date (ISO format)	Yes
items	Array of line items	Yes
payment_methods	Array of allowed payment methods ("card", "ach", "mail")	Yes
card_processor_id	Processor ID for card payments (can be empty string)	Yes
ach_processor_id	Processor ID for ACH payments (can be empty string)	Yes
send_via	Notification method ("email", "text", "both", "none")	Yes

Line Item Fields

Parameter	Description	Required
status	"pending" or "paid"	Yes
name	Item name	No
description	Item description	No
unit_price	Price in cents (100 = $1.00)	Yes
quantity	Quantity of item	Yes

Get Invoice

Retrieves details for a specific invoice including its status, line items, and payment information.

Search Invoices

Search Parameters

Parameter	Description
id	Object with operator ("=" or "!=") and value
amount_due	Object with operator ("=", "!=", "<", ">") and value
date_due	Object with start_date and end_date (ISO format)
limit	Maximum records to return (0-100)
offset	Number of records to skip

Update Invoice

Updates an existing invoice. Parameters are the same as for creating an invoice.

Delete Invoice

Deletes the specified invoice.

Invoice Features

• Partial Payments: Enable with allow_partial_payment parameter
• Tax Handling: Apply at invoice level with enable_tax or at item level with taxable
• Multiple Payment Methods: Support for card, ACH, and mail payments
• Custom Messaging: Include messages to customers with the message parameter
• Notifications: Send via email, text, or both with the send_via parameter

Customer Management

Create Customer

Key Parameter	Description
id	Optional custom ID (max 40 chars a-z, A-Z, 0-9)
description	Text description (max 255 chars)
flags	Array of settings (e.g., "surcharge_exempt")
default_payment	Object containing payment details (card, ach, token, etc.)
default_billing_address	Object containing billing address details
default_shipping_address	Object containing shipping address details

Get Customer

Search Customers

Search by ID, name, address, payment details, or date ranges.

Update Customer

Delete Customer

Address Management

Create Address

Key Parameter	Description
first_name, last_name	Contact name
company	Company name
line_1, line_2	Street address and additional details
city, state, postal_code, country	Location details
email, phone, fax	Contact information

Update Address

Delete Address

Payment Method Management

Create Payment Method

Endpoints vary by payment type:

• POST /api/vault/customer/{id}/card - Create card
• POST /api/vault/customer/{id}/ach - Create ACH
• POST /api/vault/customer/{id}/token - Create with token
• POST /api/vault/customer/{id}/applepay - Create with Apple Pay
• POST /api/vault/customer/{id}/googlepay - Create with Google Pay

Card payment parameters:

Parameter	Description	Required
number	Card number	Yes
expiration_date	Format: "MMYY" or "MM/YY"	Yes

Update Payment Method

Endpoints vary by payment type:

• POST /api/vault/customer/{id}/card/{payment_id} - Update card
• POST /api/vault/customer/{id}/ach/{payment_id} - Update ACH
• POST /api/vault/customer/{id}/token/{payment_id} - Update token

Delete Payment Method

• DELETE /api/vault/customer/{id}/card/{card_id} - Delete card
• DELETE /api/vault/customer/{id}/ach/{ach_id} - Delete ACH

Overview

Tokenizer API provides a JavaScript implementation that injects hosted payment fields onto a client's website. This keeps the client outside the scope of PCI while maintaining control over transaction processing.

Basic Implementation

<html>
  <head>
    <script src="https://sandbox.fluidpay.com/tokenizer/tokenizer.js"></script>
  </head>
  <body>
    <div id="container"></div>
    <button onclick="example.submit()">Submit</button>

    <script>
      var example = new Tokenizer({
        apikey: 'pub_XXXXXXXXXXXXXX',
        container: '#container',
        submission: (resp) => { console.log(resp) }
      })
    </script>
  </body>
</html>

Processing with Token

Sale Transaction Example

fetch("https://api.fluidpay.com/api/transaction", {
  method: "POST",
  headers: {
    "Authorization": "APIKEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "type": "sale",
    "amount": 1112,
    "payment_method": {
      "token": "<tokenizer token>"
    }
  })
})

Customer Vault Example

fetch("https://api.fluidpay.com/api/customer", {
  method: "POST",
  headers: {
    "Authorization": "APIKEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "description": "test description",
    "payment_method": {
      "token": "<tokenizer token>"
    },
    "billing_address": {
      "first_name": "John",
      "last_name": "Smith",
      // additional billing details
    }
  })
})

Advanced Configuration

Multiple Payment Types

var example = new Tokenizer({
  apikey: 'pub_XXXXXXXXXXXXXX',
  container: '#container',
  submission: (resp) => { console.log(resp) },
  settings: {
    payment: {
      types: ['card', 'ach'], // Enable both card and ACH
      ach: {
        sec_code: 'web',
        showSecCode: false,
        verifyAccountRouting: false
      },
      card: {
        strict_mode: false, // Set true for 19-digit cards
        requireCVV: false
      }
    }
  }
})

Fee Calculation

var tokenizer = new Tokenizer({
  apikey: 'pub_XXXXXXXXXXXXXX',
  amount: 100,
  container: '#container',
  settings: {
    payment: {
      calculateFees: true,
      processorId: '12345' // Optional
    }
  },
  submission: (resp) => { console.log(resp) }
})

3DS Integration (PAAY)

var example = new Tokenizer({
  apikey: "pub_XXXXXXXXXXXXXX",
  container: '#container',
  submission: (resp) => { console.log(resp.paay) },
  settings: {
    paay: {
      sandbox: false,
      forceDisabled: false,
      rejectChallenges: []
    }
  }
});

// Must include amount for payment authentication
example.submit("5.55");

Form Styling

var example = new Tokenizer({
  apikey: 'pub_XXXXXXXXXXXXXX',
  container: '#container',
  settings: {
    styles: {
      'body': {
        'color': '#ffffff'
      },
      'input': {
        'color': '#ffffff',
        'border-radius': '8px',
        'background-color': '#ffffff40',
        'border': 'none'
      },
      '.payment .cvv input': {
        'border': 'solid 1px #ffffff'
      }
    }
  }
})

Key Methods & Callbacks

Available callbacks in Tokenizer initialization:

• submission - Called after form submission with token or error
• onLoad - Called when iframe is loaded
• onPaymentChange - Called when payment type changes
• validCard - Called when a valid card is entered (includes BIN data)
• achOnChange - Called when SEC code or account type changes
• magStripeSwipe - Called when a card is swiped

Available methods:

• setError('fieldName') - Highlight field with error
• setExpDate('MM/YY') - Set expiration date
• submit() - Submit the form
• isSurchargeable(state, binData) - Check if card is surchargeable

Integration Notes

Pay Now Button Implementation

1. Add a button to your website with "Pay Now" text
2. Log in to Control Panel → Simple Payments/Pages
3. Choose your form and copy the Page URL
4. Set the URL on your button

<a href="https://yourdomain.com/spp/example-page">Pay Now</a>

URL Parameters for Customization

Custom Fields

Prefill custom fields using field IDs and values:

/spp/example-page?custom_fields=field1ID:value,field2ID:value

Example: /spp/beef_jerky?custom_fields=cotpggp97i67muer2dd0:meat,coyqg1p97i67muer2dd1:spicy

Products

Add products with quantity and price:

/spp/example-page?add_products=productID:quantity:price,productID:quantity:price

Example: /spp/beef_jerky?add_products=cjocdq45co1epquvdn60:2:8.23,cjocdq45co1epquvdn61:1:3.50

Plan

Select a plan automatically:

/spp/example-page?add_plan=planID

Amount

Set a preset amount (in cents):

/spp/example-page?add_amount=100

Custom Amount

Prefill a custom amount:

/spp/example-page?add_custom_amount=1.00

API Reference

Create Product

Parameter	Type	Description	Required
sku	string	Product SKU	Yes
name	string	Display name	Yes
price	unsigned int	Unit price in cents	Yes
fixed_amount	boolean	Lock amount or allow customization	Yes
fixed_qty	boolean	Lock quantity or allow customization	Yes
description	string	Item description (max 254 chars)	Yes
img	string	Base64 encoded product image	No

Create Simple Payments Page

Parameter	Type	Description	Required
form_type	string	Page type (e.g., "donation")	Yes
slug	string	URL slug (appended to /spp/)	Yes
name	string	Display name	Yes
title	string	Page title	Yes
description	string	Page description	Yes
payment_settings	array	Payment types to accept (card, ach)	Yes
layout	string	Page layout	Yes
success_url	string	Redirect URL after successful payment	No

Quick Integration

Add a product to cart and send customers to checkout with a single line of code:

<a href="https://sandbox.fluidpay.com/checkout/{public_cart_hash}?add_products={public_product_hash}">Buy Now</a>

Basic Setup

1. Include the Script

<script src="https://sandbox.fluidpay.com/cart/cart.js"></script>
<script>
  var cart = new Cart({
    cartID: '55e8cb7a-2d50-2235-a546-166e8bcp1569', // Your cart ID from control panel
    checkout_url: 'https://sandbox.fluidpay.com', // Sandbox or production URL
    cancel_url: 'http://yoursite.com/cancel', // Redirect on cancellation
    success_url: 'http://yoursite.com/success', // Redirect on success
  })
</script>

2. Add Product Buttons

Add to cart (stay on page):

<button onclick="cart.addProduct('ProductID_GOES_HERE')">Add to Cart</button>

Add to cart and checkout immediately:

<button onclick="cart.addProductCheckout('ProductID_GOES_HERE')">Buy Now</button>

Checkout button for cart items:

<button onclick="cart.checkout()">Checkout</button>

Advanced Features

Custom Donation/Variable Pricing

<input id="price" type="number" value="0" />
<button onclick="addDonation()">Donate</button>

<script>
  function addDonation() {
    var price = document.getElementById('price').value
    cart.addProductCheckout('product_id', 1, price)
  }
</script>

Variable Products (Quantity and Price)

Specify quantity and price in the URL:

<a href="https://sandbox.fluidpay.com/checkout/{cart_hash}?add_products={product_hash}:{quantity}:{amount}">Buy Now</a>

Custom Fields

Pre-populate custom fields with values:

<a href="https://sandbox.fluidpay.com/checkout/{cart_id}?custom_fields={field_id}:{value}">Checkout Now</a>

JavaScript Methods

Event Handlers

onChange: Triggered when products are added/removed

var cart = new Cart({
  onChange: (data) => {
    var available_products = data.available_products
    var cart_products = data.cart_products
    var totals = data.totals
  }
})

onError: Triggered on errors

var cart = new Cart({
  onError: (err) => {
    alert(err)
  }
})

Cart Methods

Method	Description
getProductByID('productID')	Returns product information
getCartProducts()	Returns available products for the cart
addProduct('productID', qty, price)	Adds product to cart
addProductCheckout('productID', qty, price)	Adds product and redirects to checkout
removeProduct('productID')	Removes product from cart
checkout()	Redirects to checkout page

Overview

Webhooks provide real-time updates for events in the Fluidpay system, eliminating the need for polling. They're triggered when transactions are processed within the gateway platform.

How to Enable

Webhooks can be enabled in the merchant control panel under "Manage" → "Settings" → "Webhooks".

Security

Webhook requests include a Signature header that is HMAC SHA-256 signed and then base64 URL encoded.

Signature Verification

1. Retrieve the Signature header from the webhook request
2. Base64 URL decode the signature
3. Use HMAC SHA-256 to verify the signature using your signature UUID from the control panel

// Golang verification example
package main

import (
    "bytes"
    "crypto/hmac"
    "crypto/sha256"
    "encoding/base64"
    "fmt"
)

func verifySignature(body []byte, signature string, secret string) bool {
    // Hash body to create signature
    hash := hmac.New(sha256.New, []byte(secret))
    hash.Write(body)
    expectedSignature := hash.Sum(nil)
    
    // Base64 decode the received signature
    receivedSignature, err := base64.RawURLEncoding.DecodeString(signature)
    if err != nil {
        return false
    }
    
    // Compare signatures
    return bytes.Equal(expectedSignature, receivedSignature)
}

Acknowledge and Retry

Webhook notifications are processed within seconds of a transaction being processed. Important handling details:

• Timeout: 5 seconds
• Expected response: HTTP 200
• Retry schedule: 5-minute exponential backoff
• Retry period: Up to 24 hours

Response Format

{
    "transaction_id": "", 
    "account_type": "merchant",
    "account_type_id": "testmerchant12345678",
    "action_at": "2020-10-08T18:45:39.053107-05:00",
    "data": {},  // Payload varies by webhook type
    "msg": "success",
    "status": "success",
    "type": "transaction"
}

Webhook Types

Category	Type Values
Transaction	test, transaction_create, transaction_update, transaction_void, transaction_capture, transaction_settlement
Card Sync	transaction_automatic_account_updater_vault_update, transaction_automatic_account_updater_vault_iw
Settlement	settlement_batch

Status Values

Webhook Type	Possible Status Values
Transaction	unknown, declined, authorized, pending_settlement, settled, voided, refunded, returned, late_return, pending, partially_refunded, flagged, flagged_partner
Card Sync	updated_card
Settlement	No status field

Setup Process

1. Activate Apple Pay Service under Settings > Services
2. After activation, the Apple Pay tab will appear in Settings
3. Use this tab to manage certificates and register domain names

After activation, Apple Pay becomes available as a payment method for Invoices, Shopping Cart, and Simple Payments.

Domain Registration

Simple Domain Registration

The easiest method requiring no Apple Developer account:

1. Go to Settings > Apple Pay
2. Click Add New Certificate then Custom Configuration
3. Add up to 100 domain names using the Add URL button
4. Download the Domain Verification file and make it available on your domains
5. Test verification file availability using the link below each URL textbox
6. Save your configuration

Advanced Domain Registration

Requires an Apple Developer License:

Merchant Identity Certificate

1. Create a private key and CSR:

   openssl req -new -newkey rsa:2048 -nodes -keyout applepay.key -out applepay.csr -subj '/O=Company Name/C=US'

2. Upload the applepay.csr file to your Apple Developer Portal
3. Download the Merchant Certificate (merchant_id.cer)
4. Convert to PEM format:

   openssl x509 -inform der -in merchant_id.cer -out merchant_id.pem

5. In Fluidpay, go to Settings > Apple Pay > Create Advanced
6. Copy and paste the contents of merchant_id.pem and applepay.key to the appropriate fields

Payment Processing Certificate

1. Create a private key:

   openssl ecparam -out private.key -name prime256v1 -genkey

2. Create a CSR:

   openssl req -new -sha256 -key private.key -nodes -out request.csr

3. Upload request.csr to your Apple Developer Portal
4. Download the processing certificate (apple_pay.cer)
5. Convert to PEM format:

   openssl x509 -inform DER -outform PEM -in apple_pay.cer -out ApplePay.crt.pem

6. Convert the private key:

   openssl x509 -inform DER -outform PEM -in apple_pay.cer -out temp.pem
   openssl pkcs12 -export -out key.p12 -inkey private.key -in temp.pem
   openssl pkcs12 -in key.p12 -out ApplePay.key.pem -nocerts -nodes

7. In Fluidpay, paste the contents of both ApplePay.crt.pem and ApplePay.key.pem in the appropriate fields

Implementation Methods

1. Using with Tokenizer

Add the Tokenizer script to your page:

<script src="https://{PAYMENT_PROVIDER_URL}/tokenizer/tokenizer.js"></script>

Initialize Tokenizer with Apple Pay settings:

var tokenizer = new Tokenizer({
  apikey: 'pub_XXXXXXXXXXX',
  container: '#container',
  settings: {
    payment: {
      types: ['card', 'apple_pay']
    }
  },
  submission: (resp) => {
    console.log(resp)
  }
})

2. Using with Apple Pay JS

Add the Apple Pay SDK script:

<script crossorigin src="https://applepay.cdn-apple.com/jsapi/1.latest/apple-pay-sdk.js"></script>

Add an Apple Pay button to your page:

<apple-pay-button buttonstyle="black" type="plain" locale="en-US" onclick="onApplePayButtonClicked()"></apple-pay-button>

Create a payment request and handle the payment:

function onApplePayButtonClicked() {
  // Create ApplePaySession
  const session = new ApplePaySession(6, {
    countryCode: 'US',
    currencyCode: 'USD',
    merchantCapabilities: ['supports3DS'],
    supportedNetworks: ['visa', 'masterCard', 'amex', 'discover'],
    total: {
      label: 'Your Store Name',
      amount: '15.00'
    }
  });

  // Setup event handlers
  session.onvalidatemerchant = (event) => {
    // Validate merchant with your server
  };

  session.onpaymentauthorized = (event) => {
    // Process payment with your server
  };

  // Begin payment
  session.begin();
}

3. Using with Payment Request API

This approach provides a more standardized interface across browsers:

if (window.PaymentRequest) {
  const supportedPaymentMethods = [
    {
      supportedMethods: 'https://apple.com/apple-pay',
      data: {
        version: 3,
        merchantIdentifier: 'merchant.com.yourdomain',
        merchantCapabilities: ['supports3DS'],
        supportedNetworks: ['visa', 'masterCard', 'amex', 'discover']
      }
    }
  ];

  const paymentDetails = {
    total: {
      label: 'Total',
      amount: { currency: 'USD', value: '15.00' }
    }
  };

  const request = new PaymentRequest(supportedPaymentMethods, paymentDetails);
  
  request.show()
    .then(paymentResponse => {
      // Process payment
      return paymentResponse.complete('success');
    })
    .catch(err => console.error('Payment error:', err));
}

Styling Apple Pay Buttons

You can customize Apple Pay buttons with CSS variables:

apple-pay-button {
  --apple-pay-button-width: 300px;
  --apple-pay-button-height: 50px;
  --apple-pay-button-border-radius: 3px;
  --apple-pay-button-padding: 0px 0px;
  --apple-pay-button-box-sizing: border-box;
}

Overview

WalletJS enables quick integration of Apple Pay and Google Pay on your website, allowing customers to pay with cards stored in their digital wallets.

Google Pay Integration

Setup

1. Create a merchant account in the Google Pay Business Console
2. Add the WalletJS script to your website

Basic Implementation

<!-- Add WalletJS script -->
<script src="https://app.fluidpay.com/walletjs/walletjs.js"></script>

<script>
  const settings = {
    container: '#container',
    merchantName: 'Your Store Name',
    merchantId: 'YOUR_GOOGLE_MERCHANT_ID',
    gatewayMerchantId: 'YOUR_PUBLIC_API_KEY',
    allowedCardNetworks: ['VISA', 'MASTERCARD'],
    allowedCardAuthMethods: ['PAN_ONLY'],
    transactionInfo: {
      countryCode: 'US',
      currencyCode: 'USD',
      totalPrice: '1.23'
    },
    onGooglePaymentButtonClicked: paymentDataRequest => {
      paymentDataRequest
        .then(paymentData => {
          // Get token to send to your server
          const token = paymentData.paymentMethodData.tokenizationData.token;
          console.log(token);
        }).catch(err => {
          console.log(err);
        })
    }
  }
  
  let gp = new walletjs.GooglePay(settings);
</script>

<!-- Button container -->
<div id="container"></div>

Key Settings

Setting	Description
container	Element ID or reference where button will appear
merchantName	Your business name (displayed in payment sheet)
merchantId	Your Google Pay merchant ID
gatewayMerchantId	Your Fluidpay public API key
allowedCardNetworks	Accepted networks: AMEX, DISCOVER, JCB, MASTERCARD, VISA
allowedCardAuthMethods	Authentication methods: PAN_ONLY, CRYPTOGRAM_3DS

Processing Transactions

Send the token to your server and make an API call:

// API call example
{
  "type": "sale",
  "amount": 123,
  "payment_method": {
    "google_pay_token": "TOKEN_STRING_HERE"
  }
}

Apple Pay Integration

Setup

1. Configure Apple Pay in your Fluidpay merchant dashboard (Settings → Apple Pay)
2. Add the WalletJS script to your website

Basic Implementation

<!-- Add WalletJS script -->
<script src="https://app.fluidpay.com/walletjs/walletjs.js"></script>

<script>
  const ap = new walletjs.ApplePay({
    key: "YOUR_APPLE_PAY_KEY",
    domain: "app.fluidpay.com", // Use sandbox.fluidpay.com for testing
    
    payment: {
      merchantCapabilities: ["supports3DS", "supportsCredit", "supportsDebit"],
      supportedNetworks: ["visa", "masterCard", "discover"],
      countryCode: "US",
      version: 3,
      merchantIdentifier: "merchant.your.identifier",
      requiredBillingContactFields: ['email', 'name', 'phone', 'postalAddress']
    },
    
    details: {
      total: {
        label: "Total Amount",
        amount: { currency: "USD", value: "10.61" }
      }
    },
    
    options: {
      requestShipping: false
    }
  });

  function submitApplePay() {
    var resp = ap.submit();
    console.log(resp);
  }
</script>

<!-- Apple Pay button -->
<button type="button" onclick="submitApplePay()">Apple Pay</button>

Key Settings

Setting	Description
key	Your Apple Pay certificate ID from Fluidpay dashboard
merchantIdentifier	Your Apple merchant identifier
supportedNetworks	Accepted networks: amex, discover, masterCard, visa
merchantCapabilities	Capabilities: supports3DS, supportsCredit, supportsDebit

Processing Transactions

Send the token to your server and make an API call:

// API call example
{
  "type": "sale",
  "amount": 123,
  "payment_method": {
    "apple_pay_token": {
      "temporary_token": "TOKEN_HERE"
    }
  }
}