Confirm session with a processor token

POST

/v1/hosted-sessions/{sessionId}/confirm

curl --request POST \
  --url https://api.govifi.com/v1/hosted-sessions/example/confirm \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "processor_token": "example", "method": "card", "save_method": true, "billing_details": { "cardholder": "example", "zip": "example", "street": "example", "street2": "example", "city": "example", "state": "example", "country": "example", "phone": "example", "email": "example" }, "challenge_response": { "type": "hcaptcha", "token": "example", "code": "example" }, "payment_method": { "card": { "last4": "example", "exp_month": 1, "exp_year": 1, "bin": "example", "card_brand": "example" }, "ach": { "bank_name": "example", "routing_number": "example", "account_number_suffix": "example", "account_type": "checking" } }, "ach_authorization": { "sec_code": "web", "accepted_at": "2026-04-15T12:00:00Z" }, "duplicate_acknowledged": true }'

• Production
• Sandbox

Authorizations

• sessionCredential

Parameters

Path Parameters

sessionId

required

string

/^cs_[A-Za-z0-9]+$/

Header Parameters

Idempotency-Key

string

Optional client-generated key that makes confirm retries idempotent. A retry carrying the same key returns the original result instead of re-charging. Confirm is single-use on success — a second confirm WITHOUT the matching key returns 409 already_confirmed.

Request Body ^required

Media type application/json

object

processor_token

required

Token from Zift/Stripe/etc. tokenization

string

method

required

string

Allowed values: card ach apple_pay paypal

save_method

Save for future use (requires session.setup_future_usage != off)

boolean

billing_details

object

cardholder

string

zip

string

street

string

street2

string

city

string

state

string

country

string

phone

string

email

string

challenge_response

Payer’s solution to the active challenge, supplied on confirm.

object

type

required

string

Allowed values: hcaptcha turnstile sms email

token

Captcha response token (hcaptcha/turnstile).

string

code

Verification code (sms/email).

string

payment_method

Tokenized, non-PCI method metadata the processor needs to charge the processor_token. Never carries PAN or CVV. Supply card for card payments, ach for bank payments.

object

card

object

last4

string

exp_month

integer

exp_year

integer

bin

string

card_brand

string

ach

object

bank_name

string

routing_number

string

account_number_suffix

string

account_type

string

Allowed values: checking savings

ach_authorization

ADDITIVE (rfc-ach-authorization.md). The NACHA authorization the payer accepted for an ACH debit, recorded with the captured payment. Sent only for an authorized ACH method.

object

sec_code

required

NACHA Standard Entry Class — web (internet), tel (telephone/agent), ppd.

string

Allowed values: web tel ppd

accepted_at

required

When the payer accepted the authorization affirmation (ISO8601).

string format: date-time

duplicate_acknowledged

Set true to proceed despite a detected duplicate payment (“submit anyway”).

boolean

Responses

200

Payment succeeded

Media type application/json

object

session_id

string

status

string

Allowed values: succeeded

transaction_id

Incidental processor (Zift) transaction id. Prefer payment_uid as the stable reference for recording/reconciliation.

string

payment_uid

ADDITIVE (see rfc-payment-uid-confirm.md). Canonical PaymentApi payment id (e.g. “P-…”) for the captured sale — the stable, account-scoped identifier hosts should record and later verify against. Unlike transaction_id it never changes and is unique per account.

string

amount

integer

convenience_fee

integer

total_amount

integer

method

string

last4

string

card_type

string

saved_method_id

Set when save_method=true and setup_future_usage allowed

string

receipt_url

string format: uri

redirect_url

For hosted flow — signed success_url

string format: uri

signature

HMAC over session_id+transaction_id, host should verify before trusting redirect

string

Example

{
  "status": "succeeded"
}

400

Payment declined (decline code in Error.code) or 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"
}

403

A fraud challenge is required or the response was invalid (challenge_required / challenge_failed), or the session credential is wallet-scoped and may not pay (insufficient_scope).

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"
}

409

Duplicate payment (resubmit with duplicate_acknowledged=true), OR the session was already confirmed (already_confirmed) — confirm is single-use on success. Retrying with the original Idempotency-Key returns the original result instead of a 409.

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"
}