Fluidpay Gateway

https://sandbox.fluidpay.com/docs/
Admin
Fluidpay Gateway is a comprehensive payment processing platform offering a RESTful API, secure...
Tokens:149,740
Snippets:610
Trust Score:8.4
Update:8 months ago
Show doc for...
Tokens:
Raw
### Make a First Charge (Sale) using JavaScript Fetch API

Source: https://sandbox.fluidpay.com/docs/api/quickstart

This example demonstrates how to perform a sale transaction using the FluidPay API. It requires a 'type', 'amount' (in cents), and 'payment_method' details. Ensure amounts are sent in cents.

```javascript
fetch("https://sandbox.fluidpay.com/api/transaction", {
  method: "POST",
  headers: {
    "Authorization": "<APIKEY>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "type": "sale",
    "amount": 1299,
    "payment_method": {
      "card": {
        "number": "4111111111111111",
        "expiration_date": "12/30",
        "cvc": "123"
      }
    }
  })
})
.then(response => response.json())
.then(data => console.log(data));
```

--------------------------------

### Base URL & Authentication

Source: https://sandbox.fluidpay.com/docs/api/quickstart

Details on the base URL for sandbox requests and how to authenticate using an API key.

```APIDOC
## Base URL & Authentication

Send HTTPS requests to the sandbox base URL with an **Authorization** header using an API key (`api_***`), and `Content-Type: application/json`.

**Base URL:** `https://sandbox.fluidpay.com`

**Headers:**
```
Authorization: api_xxx...
Content-Type: application/json
```

**Note:** Public keys (`pub_***`) are client-side only.
```

--------------------------------

### Troubleshooting Common Errors

Source: https://sandbox.fluidpay.com/docs/api/quickstart

Guidance on resolving common issues such as unauthorized access and understanding gateway/processor codes.

```APIDOC
## Troubleshooting Common Errors

### Description
This section provides guidance on resolving common error scenarios encountered when interacting with the FluidPay API, including authentication problems and interpreting transaction-specific codes.

### Method
Any

### Endpoint
Any

### Parameters
N/A

### Request Example
N/A

### Response
#### Common Error Types
- **Unauthorized errors**: Refer to the 'Unauthorized' section in the Requests documentation for details on missing Authorization headers, API key validity, restrictions, and environment configuration issues.
- **Gateway/Processor Codes**: Consult the 'Response Codes' section within the Transactions documentation for a comprehensive list and explanation of various response code ranges and their meanings.
```

--------------------------------

### Correlation ID for Support

Source: https://sandbox.fluidpay.com/docs/api/quickstart

Explains the purpose and usage of the `x-correlation-id` header for support and troubleshooting.

```APIDOC
## Correlation ID for Support

### Description
Every response from the FluidPay API includes a unique `x-correlation-id` in the response headers. This ID is crucial for support teams to trace and troubleshoot issues by looking up transaction logs. Always provide this ID when contacting support.

### Method
Any

### Endpoint
Any

### Parameters
#### Response Headers
- **x-correlation-id** (string) - A unique identifier for the request/response pair, used for logging and support.

### Request Example
N/A

### Response
#### Success Response (200) / Error Response
- **x-correlation-id** (string) - The unique identifier for this interaction.

#### Response Example (Header)
x-correlation-id: a1b2c3d4-e5f6-7890-1234-567890abcdef

### Further Information
See the Correlation ID documentation for more in-depth details.
```

--------------------------------

### HTML Structure for Tokenizer Integration

Source: https://sandbox.fluidpay.com/docs/wallets/applepay

Basic HTML structure to include the Tokenizer JavaScript library and a placeholder div for the payment interface. This sets up the client-side environment for Apple Pay integration.

```html
<script src="https://{PAYMENT_PROVIDER_URL}/tokenizer/tokenizer.js"></script>
<div id="payment-container"></div>
```

--------------------------------

### POST /api/transaction - Your First Charge (Sale)

Source: https://sandbox.fluidpay.com/docs/api/quickstart

Initiates a sale transaction, authorizing and capturing the payment in a single call. Requires type, amount (in cents), and payment method details.

```APIDOC
## POST /api/transaction - Sale

### Description
Initiates a sale transaction, authorizing and capturing the payment in a single call. Requires `type`, `amount` (in cents), and one `payment_method` (e.g., `card`). Amounts like `$12.99` must be sent as `1299`.

### Method
`POST`

### Endpoint
`https://sandbox.fluidpay.com/api/transaction`

### Parameters
#### Request Body
- **type** (string) - Required - The transaction type, e.g., `"sale"`.
- **amount** (integer) - Required - The transaction amount in cents.
- **payment_method** (object) - Required - Contains payment details.
  - **card** (object) - Required if using card payment.
    - **number** (string) - Required - The credit card number.
    - **expiration_date** (string) - Required - The expiration date in `MM/YY` format.
    - **cvc** (string) - Required - The card verification code.
- **idempotency_key** (string) - Optional - A UUID to prevent duplicate requests.
- **idempotency_time** (integer) - Optional - Time-to-live for idempotency key in seconds.

### Request Example
```json
{
  "type": "sale",
  "amount": 1299,
  "payment_method": {
    "card": {
      "number": "4111111111111111",
      "expiration_date": "12/30",
      "cvc": "123"
    }
  }
}
```

### Response
#### Success Response (200)
- **transaction_id** (string) - The unique identifier for the transaction.
- **status** (string) - The status of the transaction (e.g., `approved`, `declined`).
- **correlation_id** (string) - A unique ID for tracking the request, found in response headers.

#### Response Example
```json
{
  "transaction_id": "txn_12345abcde",
  "status": "approved",
  "message": "Transaction approved."
}
```
```

--------------------------------

### Authorize a Transaction in JavaScript

Source: https://sandbox.fluidpay.com/docs/api/quickstart

This example demonstrates how to authorize a transaction without immediately capturing the funds. This is useful for pre-authorizing a payment that will be captured later. The 'type' should be set to 'authorize'.

```javascript
fetch("https://sandbox.fluidpay.com/api/transaction", {
  method: "POST",
  headers: {
    "Authorization": "APIKEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "type": "authorize",
    "amount": 1299,
    "payment_method": {
      "card": {
        "number": "4111111111111111",
        "expiration_date": "12/30",
        "cvc": "123"
      }
    }
  })
})
.then(response => response.json())
.then(data => console.log(data));
```

--------------------------------

### Search Transactions using POST Request

Source: https://sandbox.fluidpay.com/docs/api/quickstart

This endpoint allows you to search for transactions using various filters such as date ranges, amounts, and processor information. If no 'created_at' range is specified, the search defaults to the last four months.

```http
POST https://sandbox.fluidpay.com/api/transaction/search
```

--------------------------------

### POST /api/transaction/search

Source: https://sandbox.fluidpay.com/docs/api/quickstart

Searches for transactions using various filters. If no date range is provided, it defaults to the prior four months.

```APIDOC
## POST /api/transaction/search

### Description
Searches for transactions using various filters such as date ranges, amount, and processor. If no `created_at` range is provided, the default is the prior four months.

### Method
`POST`

### Endpoint
`https://sandbox.fluidpay.com/api/transaction/search`

### Parameters
#### Request Body
- **created_at** (object) - Optional - Filters transactions by creation date.
  - **start** (string) - Optional - Start date in ISO 8601 format (e.g., `YYYY-MM-DDTHH:MM:SSZ`).
  - **end** (string) - Optional - End date in ISO 8601 format (e.g., `YYYY-MM-DDTHH:MM:SSZ`).
- **amount** (integer) - Optional - Filter by transaction amount in cents.
- **processor** (string) - Optional - Filter by processor name.

### Request Example
```json
{
  "created_at": {
    "start": "2023-01-01T00:00:00Z",
    "end": "2023-12-31T23:59:59Z"
  },
  "amount": 1299
}
```

### Response
#### Success Response (200)
- **transactions** (array) - A list of transaction objects matching the search criteria.
- **correlation_id** (string) - A unique ID for tracking the request, found in response headers.

#### Response Example
```json
{
  "transactions": [
    {
      "transaction_id": "txn_12345abcde",
      "status": "approved",
      "amount": 1299,
      "created_at": "2023-10-27T10:00:00Z"
    },
    {
      "transaction_id": "txn_67890fghij",
      "status": "declined",
      "amount": 500,
      "created_at": "2023-10-26T15:30:00Z"
    }
  ],
  "correlation_id": "ghi-789-jkl-012"
}
```
```

--------------------------------

### Get Customer By ID - JSON Response Example

Source: https://sandbox.fluidpay.com/docs/api/customer_vault

This JSON object represents a successful response when retrieving customer details by their ID. It includes customer information such as addresses, default settings, and payment methods. The response structure is consistent for all successful customer retrieval requests.

```json
{
  "status": "success",
  "msg": "success",
  "data": {
    "id": "952f250d-fa85-40ac-a45e-3886f98032c6",
    "owner_id": "testmerchant12345678",
    "data": {
      "customer": {
        "addresses": [
          {
            "city": "Some Town",
            "company": "Some Business",
            "country": "US",
            "email": "user@somesite.com",
            "fax": "555555555",
            "first_name": "John",
            "hash": "cV9qS6UvnnRDJCkgfitHqGrKSRfTARDsLy5zfkNNTcM=",
            "id": "bl6nqk69ku6897l45fp0",
            "last_name": "Smith",
            "line_1": "",
            "line_2": "",
            "phone": "5555555555",
            "postal_code": "60187",
            "state": "IL"
          }
        ],
        "defaults": {
          "billing_address_id": "bl6nqk69ku6897l45fp0",
          "payment_method_id": "bl6nqk69ku6897l45fq0",
          "payment_method_type": "card",
          "shipping_address_id": "bl6nqk69ku6897l45fp0"
        },
        "description": "test description",
        "payments": {
          "ach": [],
          "cards": [
            {
              "card_type": "visa",
              "expiration_date': '2020-12-31T00:00:00Z',
              'id': 'bl6nqk69ku6897l45fq0',
              'masked_number': '411111******1111'
            }
          ]
        }
      }
    },
    "created_at": "2019-08-09T09:04:00.786094073-05:00",
    "updated_at": "2019-08-09T09:04:00.786094116-05:00"
  }
}
```

--------------------------------

### Implement Apple Pay with Payment Request API

Source: https://sandbox.fluidpay.com/docs/wallets/applepay

This method uses the Payment Request API for a standardized payment flow. It checks for browser support, defines payment methods (specifically Apple Pay), and sets up payment details. The process includes merchant validation and handling the payment response, with error handling for failures.

```javascript
async function startApplePay() {
  if (!window.PaymentRequest) {
    alert('Payment Request API not supported')
    return
  }

  const paymentMethods = [{
    supportedMethods: 'https://apple.com/apple-pay',
    data: {
      version: 3,
      merchantIdentifier: '<YOUR_MERCHANT_IDENTIFIER>',
      merchantCapabilities: ['supports3DS'],
      supportedNetworks: ['amex', 'discover', 'masterCard', 'visa'],
      countryCode: 'US'
    }
  }]

  const paymentDetails = {
    total: {
      label: 'Your Store Name',
      amount: { value: '25.00', currency: 'USD' }
    }
  }

  const request = new PaymentRequest(paymentMethods, paymentDetails)

  // Handle merchant validation
  request.onmerchantvalidation = async (event) => {
    const merchantSession = await fetch(
      'https://{PAYMENT_PROVIDER_URL}/api/applepay/validatemerchant',
      {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          PKeyCompany: '<YOUR_APPLE_PAY_KEY>',
          ValidationUrl: event.validationURL
        })
      }
    ).then(r => r.json())
    
    event.complete(merchantSession)
  }

  try {
    const response = await request.show()
    
    // Process the payment on your server
    const result = await fetch('/api/process-apple-pay', {
      method: 'POST',
      body: JSON.stringify(response)
    }).then(r => r.json())

    await response.complete(result.success ? 'success' : 'fail')
  } catch (error) {
    console.error('Payment failed:', error)
  }
}
```

--------------------------------

### Automatically Select Plan in Simple Payments URL (JavaScript)

Source: https://sandbox.fluidpay.com/docs/services/simple_payments

This example demonstrates how to automatically select a payment plan on page load by using the 'add_plan' query parameter. The plan ID, obtained from the FluidPay Control Panel, is appended to the URL. This is useful for recurring billing or subscription setups.

```javascript
https://sandbox.fluidpay.com/spp/example-page?add_plan=planID

// Example
https://sandbox.fluidpay.com/spp/beef_jerky?add_plan=cron36bug2jkcqd9mij0
```

--------------------------------

### GET /api/transaction/{transactionId}

Source: https://sandbox.fluidpay.com/docs/api/quickstart

Retrieves the full details of a specific transaction using its ID.

```APIDOC
## GET /api/transaction/{transactionId}

### Description
Retrieves the full details of a specific transaction, including response codes, AVS/CVV results, and addresses.

### Method
`GET`

### Endpoint
`https://sandbox.fluidpay.com/api/transaction/{transactionId}`

### Parameters
#### Path Parameters
- **transactionId** (string) - Required - The ID of the transaction to retrieve.

### Response
#### Success Response (200)
- **transaction_id** (string) - The unique identifier for the transaction.
- **status** (string) - The status of the transaction.
- **amount** (integer) - The transaction amount in cents.
- **payment_method** (object) - Details about the payment method used.
- **response** (object) - Contains response codes and details.
- **correlation_id** (string) - A unique ID for tracking the request, found in response headers.

#### Response Example
```json
{
  "transaction_id": "txn_12345abcde",
  "status": "approved",
  "amount": 1299,
  "payment_method": {
    "card": {
      "type": "visa",
      "last_four": "1111"
    }
  },
  "response": {
    "code": "00",
    "message": "Approved"
  },
  "correlation_id": "abc-123-def-456"
}
```
```

--------------------------------

### Void an Authorized Transaction in JavaScript

Source: https://sandbox.fluidpay.com/docs/api/quickstart

This example demonstrates how to void an authorized transaction that has not yet settled. This effectively cancels the authorization. It requires the transaction ID of the pending transaction.

```javascript
fetch("https://sandbox.fluidpay.com/api/transaction/{transactionId}/void", {
  method: "POST",
  headers: {
    "Authorization": "APIKEY",
    "Content-Type": "application/json",
  },
})
.then(response => response.json())
.then(data => console.log(data));
```

--------------------------------

### Node.js Backend Example for Customer Creation and Charging

Source: https://sandbox.fluidpay.com/docs/workflows/tokenizer-customer-payment

A full Node.js example demonstrating how to create a customer with a payment token and then charge that customer using FluidPay's API. It utilizes Express.js for handling API requests.

```javascript
const express = require('express')
const app = express()

const API_KEY = process.env.GATEWAY_API_KEY  // Your SECRET key
const API_URL = 'https://sandbox.fluidpay.com'

// Step 2: Create customer from token
app.post('/api/create-customer', async (req, res) => {
  const { token, email, firstName, lastName } = req.body

  const response = await fetch(`${API_URL}/api/vault/customer`, {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      description: `${firstName} ${lastName}`,
      default_payment: { token },
      default_billing_address: {
        first_name: firstName,
        last_name: lastName,
        email: email
      }
    })
  })

  const data = await response.json()

  if (data.status === 'success') {
    // Save to your database
    await saveCustomerToDb({
      email: email,
      gatewayCustomerId: data.data.id,
      paymentMethodId: data.data.data.customer.defaults.payment_method_id
    })

    res.json({ success: true, customerId: data.data.id })
  } else {
    res.status(400).json({ success: false, error: data.msg })
  }
})

// Step 3: Charge the customer
app.post('/api/charge-customer', async (req, res) => {
  const { customerId, amount } = req.body

  const response = await fetch(`${API_URL}/api/transaction`, {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      type: 'sale',
      amount: amount,  // Amount in cents
      payment_method: {
        customer: { id: customerId }
      }
    })
  })

  const data = await response.json()

  if (data.status === 'success' && data.data.response === 'approved') {
    res.json({
      success: true,
      transactionId: data.data.id,
      authCode: data.data.response_body.card.auth_code
    })
  } else {
    res.status(400).json({
      success: false,
      error: data.data?.response || data.msg
    })
  }
})
```

--------------------------------

### Example Failed JSON Response

Source: https://sandbox.fluidpay.com/docs/api/quickstart

Illustrates a typical JSON response structure when a request fails. This format indicates the status of the operation and provides a descriptive message for the error encountered, such as an invalid postal code.

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

--------------------------------

### Apple Pay Initialization and Submission

Source: https://sandbox.fluidpay.com/docs/wallets/walletjs

This snippet demonstrates how to initialize the Apple Pay SDK with your credentials and submit a payment request when the button is clicked.

```APIDOC
## POST /walletjs/applepay

### Description
Initializes the Apple Pay SDK and handles the payment submission process.

### Method
POST (via walletjs.ApplePay.submit())

### Endpoint
N/A (Client-side SDK method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
(Implicitly handled by the `walletjs.ApplePay` constructor and `submit()` method)

**`walletjs.ApplePay` Constructor Parameters:**
- **`key`** (string) - Required - Your Apple Pay key obtained from the FluidPay control panel.
- **`domain`** (string) - Required - Your gateway domain (`sandbox.yourgateway.com` or `app.yourgateway.com`).
- **`payment`** (object) - Required - Payment configuration details:
  - **`merchantIdentifier`** (string) - Required - Your Apple merchant identifier.
  - **`merchantCapabilities`** (string[]) - Required - Capabilities like `supports3DS`, `supportsCredit`, `supportsDebit`.
  - **`supportedNetworks`** (string[]) - Required - Payment networks like `visa`, `masterCard`, `amex`, `discover`.
  - **`countryCode`** (string) - Required - ISO Alpha-2 country code (e.g., 'US').
  - **`version`** (number) - Required - Apple Pay version (use `3`).
  - **`requiredBillingContactFields`** (string[]) - Optional - Fields like `email`, `name`, `phone`, `postalAddress`.
- **`details`** (object) - Required - Transaction details:
  - **`total`** (object) - Required - Total amount details:
    - **`label`** (string) - Required - Label displayed in the payment sheet.
    - **`amount`** (object) - Required - Amount object: `{ currency: 'USD', value: '25.00' }`.
- **`options`** (object) - Optional - Additional options:
  - **`requestShipping`** (boolean) - Optional - Whether to request the shipping address.

**`submit()` Method:**
No direct parameters, but it triggers the Apple Pay sheet and returns a token upon success.

### Request Example
```javascript
const applePay = new walletjs.ApplePay({
  key: 'your-apple-pay-key',
  domain: 'sandbox.yourgateway.com',
  payment: {
    merchantIdentifier: 'merchant.com.yourcompany.app',
    merchantCapabilities: ['supports3DS', 'supportsCredit', 'supportsDebit'],
    supportedNetworks: ['visa', 'masterCard', 'amex', 'discover'],
    countryCode: 'US',
    version: 3
  },
  details: {
    total: {
      label: 'Your Store Name',
      amount: { currency: 'USD', value: '25.00' }
    }
  },
  options: {
    requestShipping: false
  }
});

function submitApplePay() {
  applePay.submit()
    .then((token) => {
      // Send token to your server
      sendToServer(token);
    })
    .catch((err) => {
      console.error('Apple Pay error:', err);
    });
}
```

### Response
#### Success Response (Promise resolves with token)
- **token** (string) - A temporary token representing the Apple Pay payment.

#### Response Example
```json
{
  "token": "<token-from-apple-pay>"
}
```
```

--------------------------------

### Error Response Format

Source: https://sandbox.fluidpay.com/docs/api/quickstart

Illustrates the standard JSON format for error responses received from the FluidPay API.

```APIDOC
## Error Response Format

### Description
This is the standard JSON structure for error messages returned by the FluidPay API. It includes a status and a message detailing the specific error encountered.

### Method
Any (This format applies to various HTTP methods)

### Endpoint
Any

### Parameters
N/A

### Request Example
N/A

### Response
#### Error Response
- **status** (string) - Indicates the outcome of the request, typically 'failed' for errors.
- **msg** (string) - A human-readable message describing the specific error.

#### Response Example
```json
{
  "status": "failed",
  "msg": "bad request error: invalid Postal Code"
}
```
```

--------------------------------

### Donation Example with Direct Checkout (HTML)

Source: https://sandbox.fluidpay.com/docs/services/cart

This comprehensive HTML example demonstrates how to implement a donation feature. It includes cart initialization, an input field for the donation amount (in cents), and a button to add the donation as a product and proceed directly to checkout using `cart.addProductCheckout()`.

```html
<html>
  <head>
    <script src="https://sandbox.fluidpay.com/cart/cart.js"></script>
    <script>
      var cart = new Cart({
        // The fields below are required
        cartID: '55e8cb7a-2d50-2235-a546-166e8bcp1569', // This is your card id from the control panel
        checkout_url: 'ENV_https://sandbox.fluidpay.com', // This is the environment you are wishing to hit, sandbox.<domain> or app.<domain>
        cancel_url: 'http://example.com/cancel', // This is the url you wish to redirect your customers to when they cancel a checkout
        success_url: 'http://example.com/success', // This is the url you wish to redirect your customers to when they complete a successful checkout
      })

      function addDonation() {
        var price = document.getElementById('price').value
        cart.addProductCheckout('product_id', 1, price) // remember to replace product_id with the product id from the control panel
      }
    </script>
  </head>
  <body>
    <input id="price" type="number" value="0" />
    <button onclick="addDonation()">Add to Cart</button>
  </body>
</html>
```

--------------------------------

### Import Tokenizer for SPAs in JavaScript

Source: https://sandbox.fluidpay.com/docs/services/tokenizer

Demonstrates how to import the Tokenizer library for use in Single Page Applications (SPAs). After importing, the Tokenizer is available globally, allowing for standard initialization with an API key, container, and submission callback.

```javascript
import './tokenizer.js'

// Now available globally
new Tokenizer({
  apikey: 'pub_XXXXXXXXXXXXXX',
  container: '#payment-form',
  submission: (resp) => { console.log(resp) }
})
```

--------------------------------

### POST /api/transaction/{transactionId}/refund

Source: https://sandbox.fluidpay.com/docs/api/quickstart

Refunds a settled transaction. Supports multiple partial refunds up to the settled total.

```APIDOC
## POST /api/transaction/{transactionId}/refund

### Description
Refunds a settled transaction. Supports multiple partial refunds up to the settled total.

### Method
`POST`

### Endpoint
`https://sandbox.fluidpay.com/api/transaction/{transactionId}/refund`

### Parameters
#### Path Parameters
- **transactionId** (string) - Required - The ID of the transaction to refund.

#### Request Body
- **amount** (integer) - Required for partial refunds, optional for full refund. The amount to refund, in cents.
- **surcharge** (integer) - Optional - Any applicable surcharge amount.

### Request Example
```json
{
  "amount": 500
}
```

### Response
#### Success Response (200)
- **transaction_id** (string) - The unique identifier for the refund transaction.
- **status** (string) - The status of the refund transaction.
- **correlation_id** (string) - A unique ID for tracking the request, found in response headers.

#### Response Example
```json
{
  "transaction_id": "ref_445566opqr",
  "status": "approved",
  "message": "Refund processed successfully."
}
```
```

--------------------------------

### Initialize Tokenizer with Custom Styles in JavaScript

Source: https://sandbox.fluidpay.com/docs/services/tokenizer

Initializes the Tokenizer with an API key, container element, and submission callback. It demonstrates how to apply custom CSS styles to various elements of the payment form, including inputs and focus states.

```javascript
var tokenizer = new Tokenizer({
  apikey: 'pub_XXXXXXXXXXXXXX',
  container: '#payment-form',
  submission: (resp) => { console.log(resp) },
  settings: {
    styles: {
      body: {
        color: '#333333'
      },
      input: {
        'border-radius': '4px',
        'border': '1px solid #cccccc',
        'padding': '10px',
        'font-size': '16px'
      },
      'input:focus': {
        'border-color': '#0066cc',
        'outline': 'none'
      },
      '.payment .cvv input': {
        'width': '80px'
      }
    }
  }
})
```

--------------------------------

### POST /api/transaction/{transactionId}/capture

Source: https://sandbox.fluidpay.com/docs/api/quickstart

Captures an previously authorized transaction. Requires the transaction ID and the amount to capture.

```APIDOC
## POST /api/transaction/{transactionId}/capture

### Description
Captures a previously authorized transaction. This is used after an `authorize` type transaction.

### Method
`POST`

### Endpoint
`https://sandbox.fluidpay.com/api/transaction/{transactionId}/capture`

### Parameters
#### Path Parameters
- **transactionId** (string) - Required - The ID of the transaction to capture.

#### Request Body
- **amount** (integer) - Required - The amount to capture, in cents.

### Request Example
```json
{
  "amount": 1299
}
```

### Response
#### Success Response (200)
- **transaction_id** (string) - The unique identifier for the capture transaction.
- **status** (string) - The status of the capture transaction.
- **correlation_id** (string) - A unique ID for tracking the request, found in response headers.

#### Response Example
```json
{
  "transaction_id": "cap_67890fghij",
  "status": "approved",
  "message": "Capture successful."
}
```
```

--------------------------------

### Configure Tokenizer for Local Development (JavaScript)

Source: https://sandbox.fluidpay.com/docs/services/tokenizer

This JavaScript snippet shows how to initialize the FluidPay Tokenizer with specific settings for local development. It includes setting the API key, the target container for the payment form, and crucially, the `url` option to point to the sandbox API endpoint, which is required for localhost environments.

```javascript
var tokenizer = new Tokenizer({
  url: 'https://sandbox.fluidpay.com',  // Required for localhost
  apikey: 'pub_XXXXXXXXXXXXXX',
  container: '#payment-form',
  submission: (resp) => { console.log(resp) }
})
```

--------------------------------

### Get All Custom Fields API Response

Source: https://sandbox.fluidpay.com/docs/api/custom_fields

Example response when retrieving all custom fields. It includes details such as ID, name, type, and associated values for each custom field.

```json
{
  "status": "success",
  "msg": "success",
  "total_count": 1,
  "data": [
    {
      "id": "d0cdss7svrv2303ovkfg",
      "name": "TESTCUSTOMFIELD",
      "group_name": "default",
      "type": "radio",
      "required": false,
      "validation_type": "open",
      "values": [
        {
          "name": "safely",
          "value": "safely"
        }
      ],
      "default": "",
      "created_at": "2025-05-05T15:51:13Z",
      "updated_at": "2025-05-05T15:51:13Z",
      "deleted_at": "0001-01-01T00:00:00Z"
    }
  ]
}
```

--------------------------------

### Add Product to Cart and Start Checkout

Source: https://sandbox.fluidpay.com/docs/services/cart

Adds a specified product to the user's cart and immediately initiates the checkout process. Replace 'ProductID_GOES_HERE' with the actual Product ID. Quantity and price are optional.

```javascript
cart.addProductCheckout('ProductID_GOES_HERE', qty, price)
```

--------------------------------

### Get Single Custom Field API Response

Source: https://sandbox.fluidpay.com/docs/api/custom_fields

An example response when fetching a single custom field by its ID. It provides all the details of that specific custom field, including its configuration and values.

```json
{
  "status": "success",
  "msg": "success",
  "data": {
    "id": "d0cdss7svrv2303ovkfg",
    "name": "TESTCUSTOMFIELD",
    "group_name": "default",
    "type": "radio",
    "required": false,
    "validation_type": "open",
    "values": [
      {
        "name": "safely",
        "value": "safely"
      },
      {
        "name": "growth",
        "value": "growth"
      }
    ],
    "default": "",
    "created_at": "2025-05-05T15:51:13Z",
    "updated_at": "2025-05-05T15:51:13Z",
    "deleted_at": "0001-01-01T00:00:00Z"
  }
}
```

--------------------------------

### Sample Transaction Response (Card)

Source: https://sandbox.fluidpay.com/docs/api/transactions_response

This snippet shows a sample response body for a successful card transaction in the FluidPay sandbox.

```APIDOC
## GET /websites/sandbox_fluidpay/transaction_response

### Description
Retrieves a sample response body for a card transaction in the FluidPay sandbox environment.

### Method
GET

### Endpoint
/websites/sandbox_fluidpay/transaction_response

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **status** (string) - The status of the transaction (e.g., "success").
- **msg** (string) - A message indicating the result of the operation.
- **data** (object) - Contains the details of the transaction.
  - **id** (string) - Unique identifier for the transaction.
  - **type** (string) - The type of transaction (e.g., "sale").
  - **amount** (integer) - The transaction amount in the smallest currency unit.
  - **tax_amount** (integer) - The tax amount.
  - **tax_exempt** (boolean) - Indicates if the transaction is tax-exempt.
  - **shipping_amount** (integer) - The shipping amount.
  - **discount_amount** (integer) - The discount amount.
  - **payment_adjustment_type** (string) - Type of payment adjustment.
  - **payment_adjustment_value** (integer) - Value of the payment adjustment.
  - **currency** (string) - The currency of the transaction (e.g., "usd").
  - **description** (string) - A description of the transaction.
  - **order_id** (string) - The associated order ID.
  - **po_number** (string) - The purchase order number.
  - **ip_address** (string) - The IP address from which the transaction was initiated.
  - **email_receipt** (boolean) - Whether an email receipt was sent.
  - **email_address** (string) - The email address for receipts.
  - **payment_method** (string) - The method used for payment (e.g., "card").
  - **response_body** (object) - Contains detailed processor-specific response information.
    - **card** (object) - Details specific to card payments.
      - **id** (string) - Processor-specific card ID.
      - **card_type** (string) - Type of card (e.g., "visa").
      - **first_six** (string) - The first six digits of the card number.
      - **last_four** (string) - The last four digits of the card number.
      - **masked_card** (string) - The masked card number.
      - **expiration_date** (string) - The card's expiration date.
      - **response** (string) - The processor's response to the transaction.
      - **response_code** (integer) - The processor's response code.
      - **auth_code** (string) - The authorization code.
      - **processor_response_code** (string) - The raw processor response code.
      - **processor_response_text** (string) - The raw processor response text.
      - **processor_type** (string) - The type of payment processor.
      - **processor_id** (string) - The processor's unique identifier.
      - **bin_type** (string) - The BIN type of the card.
      - **type** (string) - The card type (e.g., "debit").
      - **avs_response_code** (string) - AVS response code.
      - **cvv_response_code** (string) - CVV response code.
      - **processor_specific** (object) - Any additional processor-specific fields.
      - **created_at** (string) - Timestamp of creation.
      - **updated_at** (string) - Timestamp of last update.
  - **status** (string) - The overall status of the transaction (e.g., "pending_settlement").
  - **response** (string) - A general response message.
  - **response_code** (integer) - A general response code.
  - **customer_id** (string) - The ID of the customer associated with the transaction.
  - **billing_address** (object) - The billing address details.
  - **shipping_address** (object) - The shipping address details.
  - **created_at** (string) - Timestamp of transaction creation.
  - **updated_at** (string) - Timestamp of last transaction update.

#### Response Example
```json
{
  "status": "success",
  "msg": "success",
  "data": {
    "id": "b7kgflt1tlv51er0fts0",
    "type": "sale",
    "amount": 1112,
    "tax_amount": 100,
    "tax_exempt": false,
    "shipping_amount": 100,
    "discount_amount": 0,
    "payment_adjustment_type": "",
    "payment_adjustment_value": 0,
    "currency": "usd",
    "description": "test transaction",
    "order_id": "someOrderID",
    "po_number": "somePONumber",
    "ip_address": "4.2.2.2",
    "email_receipt": false,
    "email_address": "user@home.com",
    "payment_method": "card",
    "response_body": {
      "card": {
        "id": "b7kgflt1tlv51er0ftsg",
        "card_type": "visa",
        "first_six": "401200",
        "last_four": "5439",
        "masked_card": "401200******5439",
        "expiration_date": "12/20",
        "response": "approved",
        "response_code": 100,
        "auth_code": "TAS731",
        "processor_response_code": "00",
        "processor_response_text": "APPROVAL TAS731 ",
        "processor_type": "tsys_sierra",
        "processor_id": "b7kgflt1tlv51er0f1sg",
        "bin_type": "STANDARD",
        "type": "debit",
        "avs_response_code": "0",
        "cvv_response_code": "M",
        "processor_specific": {},
        "created_at": "2017-10-19T20:15:19.80368Z",
        "updated_at": "2017-10-19T20:15:20.777011Z"
      }
    },
    "status": "pending_settlement",
    "response": "approved",
    "response_code": 100,
    "customer_id": "aaaaaaaaaaaaaaaaaaaa",
    "billing_address": {
      "first_name": "John",
      "last_name": "Smith",
      "company": "Test Company",
      "address_line_1": "123 Some St",
      "address_line_2": "",
      "city": "Wheaton",
      "state": "IL",
      "postal_code": "60187",
      "country": "US",
      "phone": "5555555555",
      "fax": "5555555555",
      "email": "help@website.com"
    },
    "shipping_address": {
      "first_name": "John",
      "last_name": "Smith",
      "company": "Test Company",
      "address_line_1": "123 Some St",
      "address_line_2": "",
      "city": "Wheaton",
      "state": "IL",
      "postal_code": "60187",
      "country": "US",
      "phone": "5555555555",
      "fax": "5555555555",
      "email": "help@website.com"
    },
    "created_at": "2017-10-19T20:15:19.560708Z",
    "updated_at": "2017-10-19T20:15:20.832049Z"
  }
}
```
```

--------------------------------

### Install Magento 2.4+ Module

Source: https://sandbox.fluidpay.com/docs/webshop_integrations/magento

Steps to install the FluidPay payment gateway module for Magento 2.4+. This involves downloading, extracting, and enabling the module using Magento's command-line tools.

```bash
<magento_installation_directory>bin/magento setup:upgrade
<magento_installation_directory>bin/magento setup:di:compile
```

```bash
grep Custom_PaymentGateway <magento_installation_directory>/app/etc/config.php
```

--------------------------------

### Convert Apple Pay Certificate to PEM format

Source: https://sandbox.fluidpay.com/docs/wallets/applepay

Converts the downloaded Apple Pay certificate from DER format to PEM format using OpenSSL. This PEM-formatted certificate is required for further processing and integration.

```bash
openssl x509 -inform DER -outform PEM -in apple_pay.cer -out processing.crt.pem
```

--------------------------------

### Initialize Google Pay with WalletJS

Source: https://sandbox.fluidpay.com/docs/wallets/walletjs

Initialize the Google Pay payment interface using WalletJS. This involves specifying the button container, merchant details, allowed card networks and authentication methods, transaction information, and a callback function to handle the payment response.

```javascript
const googlePay = new walletjs.GooglePay({
  // Where to place the button
  container: '#google-pay-button',
  
  // Your merchant info
  merchantName: 'Your Store Name',
  merchantId: 'your-google-merchant-id',        // From Google Pay Business Console
  gatewayMerchantId: 'pub_XXXXXXXXXXXXXX',      // Your public API key
  
  // Payment options
  allowedCardNetworks: ['VISA', 'MASTERCARD', 'AMEX', 'DISCOVER'],
  allowedCardAuthMethods: ['PAN_ONLY', 'CRYPTOGRAM_3DS'],
  
  // Transaction details
  transactionInfo: {
    countryCode: 'US',
    currencyCode: 'USD',
    totalPrice: '25.00'
  },
  
  // Handle the response
  onGooglePaymentButtonClicked: (paymentDataRequest) => {
    paymentDataRequest
      .then((paymentData) => {
        // Get the token from Google's response
        const token = paymentData.paymentMethodData.tokenizationData.token
        
        // Send token to your server to process the payment
        sendToServer(token)
      })
      .catch((err) => {
        console.error('Google Pay error:', err)
      })
  }
})
```

--------------------------------

### Generate ECC Private Key using OpenSSL

Source: https://sandbox.fluidpay.com/docs/wallets/applepay

Generates an Elliptic Curve Cryptography (ECC) private key using OpenSSL. This key is essential for creating a Certificate Signing Request (CSR).

```bash
openssl ecparam -out processing.key -name prime256v1 -genkey
```

--------------------------------

### Tokenizer Methods

Source: https://sandbox.fluidpay.com/docs/services/tokenizer

Provides a list of available methods for interacting with the Tokenizer.

```APIDOC
## Tokenizer Methods

### Description
Provides a list of available methods for interacting with the Tokenizer.

### Methods
- **`tokenizer.submit()`**: Submit the form and generate a token.
- **`tokenizer.submit('5.00')`**: Submit with amount (required for 3DS/Paay).
- **`tokenizer.setError('cvv')`**: Highlight a field as invalid.
- **`tokenizer.setExpDate('12/25')`**: Programmatically set expiration date.
- **`tokenizer.isSurchargeable(state, bin)`**: Check if card can be surcharged.
```

--------------------------------

### Authenticate API Requests with Authorization Header

Source: https://sandbox.fluidpay.com/docs/api/quickstart

All HTTPS requests to the FluidPay API require an 'Authorization' header with your API key and a 'Content-Type' header set to 'application/json'. Public keys are for client-side use only.

```http
Authorization: api_xxx...
Content-Type: application/json
```

--------------------------------

### Create Address

Source: https://sandbox.fluidpay.com/docs/api/customer_vault

Creates a new address record associated with a customer.

```APIDOC
## POST /api/vault/customer/{ customer id }/address

### Description
Creates a new address record that will be stored within the customer record. A stored address can be used as the billing and/or shipping address on transactions processed for the customer.

### Method
POST

### Endpoint
`/api/vault/customer/{ customer id }/address`

### Parameters
#### Path Parameters
- **customer id** (string) - Required - The unique identifier for the customer to associate the address with.

#### Request Body
- **first_name** (string) - Optional - Addressee first name.
- **last_name** (string) - Optional - Addressee last name.
- **company** (string) - Optional - Company name.
- **line_1** (string) - Optional - Street address.
- **line_2** (string) - Optional - Additional delivery details.
- **city** (string) - Optional - City name.
- **state** (string) - Optional - State code (e.g., "CA").
- **postal_code** (string) - Optional - Postal code (e.g., "12345").
- **country** (string) - Optional - Country code (e.g., "US").
- **email** (string) - Optional - Email address (must be valid format, e.g., "example@mail.com").
- **phone** (string) - Optional - Phone number (e.g., "3216540987").
- **fax** (string) - Optional - Fax number (e.g., "3216540987").

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.
- **msg** (string) - A message confirming the address creation.
- **address_id** (string) - The unique identifier for the newly created address.

#### Response Example
```json
{
  "status": "success",
  "msg": "Address created successfully.",
  "address_id": "addr_789"
}
```
```
Tokens:
Raw