Skip to main content

Hosted payment form

The hosted payment form is a page operated by PaymentsAI (at secure-payments.app) where the customer completes a payment. The card data is collected on the hosted form — it never reaches your server — and the form handles 3D Secure authentication internally.

The hosted form is how PaymentsAI processes the first payment of a subscription created with a new (inactive) payment instrument.

When you use it​

Redirect the customer to the hosted form when:

  • A subscription is created with a new (inactive) payment instrument and the response returns status: "pending" with recentInvoicePaymentFormUrl.
  • An open invoice exists for a subscription and you want the customer to pay it (the invoice carries the same hosted-form URL).

You do not need to send the customer to the hosted form when:

  • A subscription is created against an already active payment instrument. PaymentsAI auto-charges renewals directly — no redirect needed.

What the hosted form does​

When the customer lands on the hosted form, PaymentsAI:

  1. Collects the card details on its own page. Your server never sees the PAN, CVV, or full card data — this keeps you out of PCI DSS scope.
  2. Submits the payment to the gateway.
  3. Handles 3D Secure internally when the issuer requests it. There is no separate challenge flow for your code to implement — the form runs it end to end. See the 3DS2 guide for the protocol detail.
  4. Activates the payment instrument once the first payment succeeds. The instrument transitions from inactive to active and auto-charges on future renewals without another redirect.
  5. Redirects the customer back to the redirectUrl you provided, substituting {id} (the transaction or subscription ID) and {result} (the outcome).

Return URL​

The hosted form returns the customer to your redirectUrl with two placeholders filled in:

https://yoursite.com/{id}/{result}
PlaceholderFilled with
{id}The ID of the entity the customer just paid for — a transaction ID for one-time charges, or the subscription/order ID (ord_xxx) for a subscription's first payment.
{result}The outcome: approved, declined, abandoned, canceled, or unknown.

Use the result for the immediate UI response (success / failure page) and confirm the final state via API polling or the offsite-payment-completed webhook — the customer may close the tab before the redirect completes. See Subscription webhooks.

Security notes​

  • The hosted form is served from a PaymentsAI-controlled domain (secure-payments.app). The card data never touches your infrastructure.
  • This is the only supported way to process the first payment of a subscription on a new payment instrument. There is no programmatic endpoint that activates an inactive instrument without a customer-driven payment. See Subscription troubleshooting for things that look like they should work but don't.