Skip to navigation
API OverviewPayments

Collect CVV

View as Markdown

Start one isolated secure collection workflow for the Session. The Gateway never receives, stores, logs, or returns the collected card digits. Card collection accepts 12–19 digits and applies Luhn validation inside the trusted payment path; security-code collection accepts exactly three digits. An accepted workflow atomically supersedes foreground Session media. While that transition or collection is active, competing foreground playback, digit collection, and playback controls are rejected; dtmf/send remains available. A 202 response is only admission. Wait for the matching collection-started webhook before sending card or security-code digits. The terminal result is delivered as a sanitized payment webhook.

See the generated payment.* webhook operations for complete payload schemas and examples.

Authentication

AuthorizationBearer

Send Authorization: Bearer <app_uuid>:<api_key> using an active API key. See Authentication for details.

Path parameters

uuidstringRequired

Session identifier.

Headers

Idempotency-KeystringOptionalformat: "^[a-zA-Z0-9._-]*$"<=128 characters

Optional key for safely retrying mutating requests. An explicitly empty header is treated like omission and does not enable replay protection. See Idempotency for details.

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.
between_digits_timeout_msintegerRequired100-10000
Milliseconds to wait between digits.
first_digit_timeout_msintegerRequired1000-300000

Milliseconds to wait for the first digit. Allowed range: 1000–300000 ms (1 second to 5 minutes), inclusive. Values below 1000 ms are not supported.

terminatorslist of enumsRequired
Distinct DTMF terminators. An empty array collects to the fixed secure length or timeout.
Allowed values:
prompt_fileslist of stringsOptional

Up to four optional HTTP/HTTPS WAV or MP3 prompts played before the secure collection window opens. The complete prompt preflight is bounded to eight seconds.

Response headers

traceparentstringOptionalformat: "^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$"=55 characters

Server-owned W3C Trace Context for correlating this response with support and observability data. It is present on successful and error responses. A valid incoming traceparent is linked to, but never becomes, the server-owned trace identifier.

Response

Command accepted for async execution
operation_uuidstring
statusenum
Allowed values:
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
404
Not Found Error
406
Not Acceptable 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
502
Bad Gateway Error
503
Service Unavailable Error