First API Call

Create a sandbox hosted checkout payment from a server and inspect the Payflow response.

This guide creates a sandbox card payment using the hosted checkout flow. It is the quickest end-to-end path because Payflow prepares the transaction, selects a configured provider through routing rules, and returns a checkout URL.

Before you start

You need:

Access to the hosted Payflow client API at https://api.ftosllc.co/client/v1.
An organization whose sandbox onboarding is complete.
A Payflow API application with sandbox credentials.
A sandbox secret key beginning with sk_test_.
Card routing configured for the sandbox environment.
Stripe or Square sandbox provider readiness if your routing rules select those providers.

The secret key is a server-side credential. Do not ship it to browsers, mobile apps, logs, or analytics tools.

1. Set environment variables

export PAYFLOW_CLIENT_API_URL="https://api.ftosllc.co/client/v1"
export PAYFLOW_SECRET_KEY="sk_test_your_key_id_your_secret"

2. Create a payment

curl -X POST "$PAYFLOW_CLIENT_API_URL/payments" \
  -H "Authorization: Bearer $PAYFLOW_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: quickstart-001" \
  -d '{
    "amountMinor": "2500",
    "currency": "USD",
    "paymentMethod": "web_card",
    "description": "Quickstart payment",
    "customer": {
      "name": "Ada Lovelace",
      "email": "[email protected]"
    },
    "metadata": {
      "orderId": "order_1001"
    },
    "successUrl": "https://checkout.example.com/success",
    "cancelUrl": "https://checkout.example.com/cancel"
  }'

amountMinor is the smallest currency unit. For USD, 2500 means $25.00.

3. Read the response

A successful response looks like:

{
  "success": true,
  "data": {
    "payflowReference": "pf_test_1f7a9d7c4a1d4a0d9c3b7a6b5e2f1010",
    "status": "prepared",
    "amountMinor": "2500",
    "currency": "USD",
    "paymentMethod": "web_card",
    "provider": "stripe",
    "routing": {
      "provider": "stripe",
      "channel": "web_card",
      "matchedRuleId": null,
      "matchedConditionIds": [],
      "fallback": true
    },
    "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_test_...",
    "preparedAt": "2026-07-07T12:00:00.000Z"
  },
  "message": null
}

Send the checkoutUrl to your user or redirect the user from your server-rendered flow.

4. Confirm the transaction later

After the provider completes or fails the payment, use the payflowReference, your own order ID, and provider callback status to reconcile the result in your application.

Common first-call errors

Message	Meaning	Fix
`Invalid API credential.`	The Bearer token does not match a Payflow publishable or secret key.	Use the full key generated for the application environment.
`API credential is not active.`	The key, application, organization, sandbox, or production access is not active.	Check application environment state and onboarding.
`Checkout return URLs must use an origin registered for this application environment.`	The success or cancel URL origin is not allowed.	Add the origin in the application environment settings.
`Card payment routing is not configured yet.`	No enabled card routing rule exists.	Configure routing rules for `web_card`.
`Hosted checkout is currently available in Sandbox only.`	Hosted checkout is intentionally sandbox-only in the current implementation.	Use component payments or wait for production hosted checkout support.

Next steps

For browser-safe card flows, read Payment components.
For bank transfers, read ACH transfers.
For credential management, read Applications and keys.