completeOrder

​​ Overview

completeOrder finishes the payment. It hands the flow to Firmly’s payment vault, which proxies into the service-binding-only /complete route, fetches the network token credentials, and submits the order to the merchant.

​​ Signature

const order = await fap.completeOrder(session, options);

​​ Parameters

• session (FlowSession, required) — A session with both flow_token and intentId set — i.e. createIntent has already run.

• options.domain (string) — Merchant domain for the order. Set here or as ClientConfig.merchantDomain — one of the two must be provided.

• options.deviceTokenOverride (string) — Device JWT for the vault’s deviceAuth. Set here or as ClientConfig.deviceToken — one of the two must be provided. Mint via POST /api/v1/browser-session.

• options.billingInfo (object) — Forwarded to vault as billing_info. Required when the agentic-pay handler cannot fall back to a billing address from the network token — vault’s place-order step validates the billing country and throws when it is missing.

• options.captchaToken (string) — Forwarded to vault as captcha_token — some merchants require it.

• options.additional (object) — Extra fields merged into vault’s additional_data object (e.g. card_art).

• options.signal (AbortSignal) — Abort the request.

​​ Returns

Promise<object> — the Wallet Complete Order response, passed through verbatim. See that page for the full response schema. It is the placed cart — cart_id, cart_status: "submitted", a platform_order_number, the total, and a payment_summary (which carries the card_art).

{
  "cart_id": "4dbaf295-93d1-452b-a7e5-a5965ca2871d",
  "cart_status": "submitted",
  "platform_order_number": "29185",
  "total": { "currency": "USD", "value": 88.99, "number": 8899, "symbol": "$" },
  "payment_summary": {
    "card_type": "Visa",
    "card_art": { "url": "https://api.firmly.work/api/v1/wallets/agentic-pay/card-art/<signed-token>" }
  }
}

​​ Failure modes

The call rejects (does not resolve) when the vault cannot place the order. Two common cases:

• Missing billing country. If the agentic-pay handler cannot fall back to a billing address from the network token, the vault’s place-order step validates the billing country and throws when it is absent. Pass options.billingInfo with a country to avoid this.
• Captcha rejection. Some merchants require a captcha; a missing or rejected options.captchaToken is surfaced as a failure from the vault. Supply a valid token when the merchant requires one.

​​ Example

const order = await fap.completeOrder(session, {
  domain: 'staging.luma.gift',
  deviceTokenOverride: browserSessionJwt,
  billingInfo: {
    first_name: 'Jane',
    last_name: 'Doe',
    country: 'US'
    // ...
  }
});

console.log('Order placed:', order);

​​ Related

• createIntent — must run first
• Wallet Complete Order API — the underlying order-placement endpoint