Sale / Auth transaction

Charge a card, authorize funds for later capture, verify a card, or issue a credit. The workhorse transaction endpoint.

Amount vs. base amount

• amount is the final amount you want charged, inclusive of any surcharges, convenience fees, and taxes you have calculated.
• base_amount lets moat calculate surcharge-style adjustments for you. Pass the pre-fee base and the system adds the surcharge at processing time using your configured fee program.

Basic fields

The minimum viable request has a type, an amount, and one payment_method.

fetch("https://sandbox.fluidpay.com/api/transaction", {
  method: "POST",
  headers: {
    "Authorization": "YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    type: "sale",
    amount: 1299,
    payment_method: {
      card: {
        number: "4111111111111111",
        expiration_date: "12/30",
        cvc: "123"
      }
    }
  })
})

Details & metadata

Optional fields that travel with the transaction and show up in reporting.

Idempotency

Optionally include an idempotency key to make retries safe. Replaying the same key within its TTL returns the result of the original attempt rather than charging a second time.

{
  "type": "sale",
  "amount": 1299,
  "idempotency_key": "7df4d862-1a3d-44c4-b3df-536aadf307b0",
  "payment_method": { "card": { ... } }
}

Payment methods

Exactly one of the following keys must appear under payment_method.

Card

Debit or credit card with keyed or swiped entry.

{
  "type": "sale",
  "amount": 1299,
  "payment_method": {
    "card": {
      "number": "4111111111111111",
      "expiration_date": "12/30",
      "cvc": "123"
    }
  }
}

Card with 3DS data

{
  "type": "sale",
  "amount": 1299,
  "payment_method": {
    "card": {
      "number": "4111111111111111",
      "expiration_date": "12/30",
      "cvc": "123",
      "cardholder_authentication": {
        "eci": "05",
        "cavv": "AAABBIcJImlkEh0gHUiCUgAAAAA=",
        "version": "2"
      }
    }
  }
}

Customer (vaulted)

Charge a payment method stored in the Customer Vault.

{
  "type": "sale",
  "amount": 1299,
  "payment_method": {
    "customer": {
      "id": "cust_abc123",
      "payment_method_id": "pm_xyz789"
    }
  }
}

Token

Charge a tokenized payment method produced by Tokenizer.

{
  "type": "sale",
  "amount": 1299,
  "payment_method": { "token": "tok_V1StGXR8_Z5jdHi6B-myT" }
}

Apple Pay

Two entry points: native ApplePay.js / Payment Request API, or the simpler Wallet.js temporary token path.

ACH

Bank account debit via Automated Clearing House.

{
  "type": "sale",
  "amount": 1299,
  "payment_method": {
    "ach": {
      "routing_number": "110000000",
      "account_number": "000123456789",
      "sec_code": "web",
      "account_type": "checking"
    }
  }
}

Terminal

Run a transaction against a physical card-present terminal you have registered on the account.

APM (alternative payment methods)

Alternative payment methods like Klarna, OXXO, Alipay, WeChat Pay, SEPA, and DragonPay.

Supported APMs

Amounts

See the dedicated Amounts page for the full breakdown of amount vs. base_amount, tax, shipping, discount, tip, and payment_adjustment handling.

Addresses

Billing addresses drive AVS (Address Verification System) and fraud scoring. Shipping addresses are required for Level 3 data.

Billing

Shipping

Same shape as billing, under shipping_address. Required for Level 3 data transactions; both billing and shipping postal codes must be present.

Line items

Itemize the products or services on the transaction. Improves receipts, reporting, and — when fully populated — Level 3 interchange rates.

Custom fields

Attach merchant-defined data to the transaction. You must first create the custom fields via the Custom Fields API.

• Keys in custom_fields are custom field IDs.
• Values are arrays of strings, even for single values.
• If your custom fields use a non-default group, include group_name on the transaction.

{
  "type": "sale",
  "amount": 1299,
  "payment_method": { "card": { ... } },
  "custom_fields": {
    "cf_order_source": ["mobile_app"],
    "cf_flags": ["gift", "priority"]
  }
}

Descriptor

Override the merchant descriptor that shows up on cardholder statements. Reduces chargebacks by making the charge recognizable. Support and formatting rules vary by processor.

Customer Vault from a transaction

Save the payment method from a successful transaction directly into the vault, without a second API call.

Email receipts

Partial payments

Set allow_partial_payment: true to accept partial authorizations where the processor returns less than the requested amount. See also the Response page for how to inspect amount_authorized versus amount.

Split transaction

If your account has Split Transactions enabled, passing split_transaction_amount (in cents) runs a second, independent transaction on the same card against a different processor. Common use: application fees. The response contains a split_transaction_response with its own transaction ID for refunds or voids.

Level 3 data

Level 3 unlocks lower interchange rates for B2B and government cards. It requires, at minimum:

• order_id
• summary_commodity_code (4 alphanumeric characters)
• ship_from_postal_code
• Billing and shipping postal_codes
• Fully populated line_items[] including commodity_code, unit_of_measure, and the usual quantity / price / tax fields

CIT / MIT (card on file)

Customer-initiated and merchant-initiated transaction indicators. Required for subsequent charges against stored credentials.

HSA / FSA

Health Savings Account and Flexible Spending Account splits.