Hosted Checkout

Hosted checkout creates a payment preparation, evaluates routing, creates a provider checkout session or link, and returns a URL.

POST /client/v1/payments

Hosted checkout is currently available in sandbox only.

Authentication

Use a server-side secret key:

Authorization: Bearer sk_test_...

The endpoint can authenticate any active client API credential, but a backend call with a secret key is the recommended integration pattern for hosted checkout.

Request body

{
  "amountMinor": "2500",
  "currency": "USD",
  "paymentMethod": "web_card",
  "description": "Invoice INV-1001",
  "customer": {
    "name": "Grace Hopper",
    "email": "[email protected]"
  },
  "metadata": {
    "invoiceId": "INV-1001"
  },
  "successUrl": "https://checkout.example.com/success",
  "cancelUrl": "https://checkout.example.com/cancel"
}

Field	Required	Notes
`amountMinor`	Yes	Positive integer or numeric string.
`currency`	Yes	Three-letter code.
`paymentMethod`	No	Defaults to `web_card`.
`description`	No	Sent to provider where supported.
`customer`	No	Name and email only.
`metadata`	No	Stored with Payflow records.
`successUrl`	Yes	Origin must be registered for the application environment.
`cancelUrl`	Yes	Origin must be registered for the application environment.

Response

{
  "success": true,
  "data": {
    "payflowReference": "pf_test_0c0ed93b0c694ec8a99f326e78d8f09d",
    "status": "prepared",
    "amountMinor": "2500",
    "currency": "USD",
    "paymentMethod": "web_card",
    "provider": "square",
    "routing": {
      "provider": "square",
      "channel": "web_card",
      "matchedRuleId": "rule_...",
      "matchedConditionIds": ["condition_..."],
      "fallback": false
    },
    "checkoutUrl": "https://square.link/u/...",
    "preparedAt": "2026-07-07T12:00:00.000Z"
  },
  "message": null
}

Redirect the customer to data.checkoutUrl.

Provider behavior

If routing selects Stripe, Payflow creates a Stripe Checkout Session with the payment amount, currency, description, customer email, and Payflow metadata.

If routing selects Square, Payflow creates a Square Online Checkout payment link with the payment amount, currency, buyer email, and Payflow reference.

If routing selects an unsupported provider for card checkout, Payflow returns 409.

URL allowlist

Both return URLs must use an origin registered for the application environment. Payflow compares only origins, not paths.

Example:

Registered origin: https://checkout.example.com
Accepted URL:       https://checkout.example.com/success
Rejected URL:       https://app.example.net/success

Failure handling

Hosted checkout can fail before a provider session is created. Common cases:

Routing rules are disabled or incomplete.
The provider is not configured for sandbox.
The return URL origin is not allowed.
The credential environment is not active.

Show message to internal operators, but use a product-specific message for end customers.