Quickstart

Your first moat API call, end to end. Takes about five minutes once you have your keys.

1. Base URL and authentication

Send HTTPS requests to the sandbox or production base URL with an Authorization header that carries your secret API key (prefixed api_) and Content-Type: application/json.

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

2. Your first charge

To process a card payment, POST to /api/transaction. The minimum required fields are type, amount (in cents), and a payment_method. Cents matter — $12.99 is 1299, not 12.99.

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"
      }
    }
  })
})
.then(r => r.json())
.then(console.log);

3. Idempotency (optional but recommended)

Add an idempotency_key (any UUID) to safely retry a request without double-charging. By default the key is valid for five minutes; override with idempotency_time in seconds.

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

4. Common flows

Sale

Authorize and capture in a single call. This is the default for most online checkouts.

{
  "type": "sale",
  "amount": 1299,
  "payment_method": { "card": { ... } }
}

Authorize, then capture

Useful when you need to confirm inventory, verify something manually, or wait for a customer action before actually taking the money. Authorize now:

{
  "type": "authorize",
  "amount": 1299,
  "payment_method": { "card": { ... } }
}

Capture when you're ready (you can capture less than the authorized amount):

{
  "amount": 1299
}

Void

Cancels a transaction before it settles. Behind the scenes this is processed as an auth reversal where the processor supports one.

Refund

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

{
  "amount": 500
}

If you omit amount, the whole transaction is refunded. You can also pass a surcharge value to control how any surcharge fee is refunded.

5. Looking up transactions

Fetch a single transaction by ID:

This returns the full transaction record including AVS and CVV response codes, address details, and any linked refund or capture IDs.

Or search across transactions with filters:

You can filter by date range, amount range, processor, customer, and more. If you don't pass a date range, the default window is the last four months.

6. Handling responses and errors

A failed request looks like this:

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

Troubleshooting

• Unauthorized errors: see the Unauthorized section in Requests for how to debug missing or wrong Authorization headers and environment mixups.
• Decline / gateway codes: see the response code reference in Response for the full list of codes and what each one means.