Skip to content
Govifi Checkout

Create a hosted session

POST
/v1/hosted-sessions
 
curl --request POST \
  --url https://api.govifi.com/v1/hosted-sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Payment-Account-Uid: example' \
  --data '{ "amount": 14650, "currency": "USD", "description": "example", "line_items": [ { "description": "example", "amount": 1, "quantity": 1, "metadata": {} } ], "customer_id": "example", "customer_email": "hello@example.com", "success_url": "https://example.com", "cancel_url": "https://example.com", "layout": "hosted", "allowed_methods": [ "card" ], "setup_future_usage": "off", "scope": "payment", "expires_in_seconds": 1800, "branding": { "logo_url": "https://example.com", "accent_color": "example", "merchant_display_name": "example" }, "required_avs_fields": [ "cardholder" ], "metadata": { "additionalProperty": "example" }, "fraud_signals": { "ip_address": "example", "user_agent": "example", "email": "hello@example.com", "phone": "example", "account_type": "example", "request_timestamp": 1, "is_authorized": true, "is_admin": true } }'

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Header Parameters

Section titled “Header Parameters ”
X-Payment-Account-Uid
required
string

Identifies the tenant (payment account) for the server-side, Cognito-admin-authenticated operations (create / update / expire). Same header /api/paymentaccounts uses.

Request Body required

Section titled “Request Body required ”
Media type application/json
object
amount
required

Cents

integer
Example 
14650
currency
required
string
Example 
USD
description
string
line_items
Array<object>
object
description
required
string
amount
required

Cents

integer
quantity
integer
default: 1
metadata
object
customer_id

Govifi customer id; if set, saved methods will be hydrated

string
customer_email
string format: email
success_url
required
string format: uri
cancel_url
required
string format: uri
layout

Hint to the component about which chrome to render

string
default: embedded
Allowed values: hosted embedded
allowed_methods
Array<string>
Allowed values: card ach apple_pay paypal
setup_future_usage
string
default: off
Allowed values: off on_session off_session
scope

Capability scope minted into the session credential. payment (default) may quote, run challenges, and confirm a charge. wallet is for saved-method management only — its credential is rejected (403 insufficient_scope) at the payment endpoints (confirm/quote-fee/challenge).

string
default: payment
Allowed values: payment wallet
expires_in_seconds
integer
default: 1800 >= 300 <= 86400
branding
object
logo_url
string format: uri
accent_color
string
/^#[0-9A-Fa-f]{6}$/
merchant_display_name
string
required_avs_fields
Array<string>
Allowed values: cardholder zip street street2 city state country phone email
metadata
object
key
additional properties
string
fraud_signals

Raw fraud/risk inputs observed by the merchant backend at session creation, forwarded so the API can enforce timing/risk server-side on confirm (API-9). Contains PII; stored server-side and never returned in the sanitized session config.

object
ip_address
string
user_agent
string
email
string format: email
phone

Phone for SMS challenges on high-risk sessions.

string
account_type
string
request_timestamp

Unix epoch milliseconds when the payment form loaded (drives timing validation).

integer format: int64
is_authorized
boolean
is_admin
boolean

Responses

Section titled “ Responses ”

201

Section titled “201 ”

Session created

Media type application/json
object
session_id
required
string
client_secret
required

The browser credential — sent as Authorization: Bearer on every browser call. Authenticates and is reusable for the chatty reads; expires with the session. Not single-use (the confirm-on-success is).

string
expires_at
required
string format: date-time
hosted_url
required
string
embed_url
required
string
Example 
{
  "session_id": "cs_3oNkLp9aBcDeFgHi",
  "client_secret": "cs_3oNkLp9aBcDeFgHi_secret_7Qx...",
  "hosted_url": "https://checkout.govifi.com/cs_3oNkLp9aBcDeFgHi",
  "embed_url": "https://checkout.govifi.com/embed/cs_3oNkLp9aBcDeFgHi"
}

400

Section titled “400 ”

Validation error

Media type application/json
object
code
required
string
Allowed values: card_declined expired_card incorrect_cvc insufficient_funds processing_error network_error session_expired validation_error origin_not_allowed rate_limited challenge_required challenge_failed duplicate_payment already_confirmed insufficient_scope
message
required
string
recoverable
boolean
request_id
string
Example 
{
  "code": "card_declined"
}

401

Section titled “401 ”

Bad or missing credential (Cognito admin token or session credential)

Media type application/json
object
code
required
string
Allowed values: card_declined expired_card incorrect_cvc insufficient_funds processing_error network_error session_expired validation_error origin_not_allowed rate_limited challenge_required challenge_failed duplicate_payment already_confirmed insufficient_scope
message
required
string
recoverable
boolean
request_id
string
Example 
{
  "code": "card_declined"
}