Create a charge

View as Markdown
Create a durable charge attempt from opaque card and security-code references. `Idempotency-Key` is required so charge admission can be replayed safely. The requested Nedarim terminal must be present in the authenticated application's operator-managed terminal allowlist; an unbound terminal is rejected before charge admission. The idempotency record stores a fingerprint of validated non-sensitive charge fields and the sanitized HTTP result, not the request body, card digits, or security code. A charge can be attempted only while the Session remains connected. After disconnect, the call-scoped card and security-code references are no longer usable. The Gateway stores only safe metadata and never receives card digits, a security code, provider credentials, or raw provider details. A provider timeout or uncertain submission is terminally reported as `indeterminate` and is never automatically submitted again. See [Payment lifecycle events](/api/payments#lifecycle-events) for complete payload schemas and examples.

Authentication

AuthorizationBearer
Application auth. Send `Authorization: Bearer <app_uuid>:<api_key>` using any active key in the app's collection. See [Authentication](https://voice-platform.docs.buildwithfern.com/api/authentication) for details.

Path parameters

uuidstringRequired

Session identifier.

Headers

Idempotency-KeystringRequiredformat: "^[a-zA-Z0-9._-]+$"<=128 characters
Required key used to make charge admission safely replayable.
Operation-IdstringOptionalformat: "uuid"

optional client-supplied lowercase RFC-4122 v4 UUID returned as operation_uuid; platform generates one when omitted; correlation metadata distinct from Idempotency-Key.

Request

This endpoint expects an object.
amountintegerRequired1-999999999
Charge amount in the currency's smallest unit.
card_uuidstringRequiredformat: "^card_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"

Opaque card reference returned by payment.card.collected.

currencyenumRequired
Allowed values:
cvv_uuidstringRequiredformat: "^cvv_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"

Opaque CVV reference returned by payment.cvv.collected.

exp_monthintegerRequired1-12
exp_yearintegerRequired2000-9999
providerenumRequired
Allowed values:
terminal_numberstringRequiredformat: "^[0-9]{7}$"

Seven-digit Nedarim Mosad terminal number for this charge. Operators must bind the terminal to the authenticated application before it can be used.

Response

Command accepted for async execution
operation_uuidstringformat: "uuid"
statusenum
already_endedtrueOptional

Optional. Set to true on idempotent terminal commands when the session was already in a terminal state at the time the request was received. Absent otherwise.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
413
Content Too Large Error
415
Unsupported Media Type Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error