Skip to main content
POST
Tokenize a card typed on a phone keypad

Authorizations

Authorization
string
header
required

You can retrieve your token by visiting your dashboard and clicking Generate API token under your profile in top right.

Body

application/json
method
string
required

Must be tokenize.

Example:

"tokenize"

cardnumber
string
required

The card number.

Example:

"4111111111111111"

cvv
string
required

The card security code.

Example:

"123"

expiry_month
string
required

Two-digit month.

Example:

"08"

expiry_year
string
required

Two-digit year.

Example:

"27"

postal_code
string
required

The cardholder's ZIP, or Canadian postal code.

Example:

"30009"

parameters
object
required

Connector parameters. Must contain sid.

Example:
transaction_id
string

Telnyx's id for the payment session, recorded for support.

Example:

"550e8400-e29b-41d4-a716-446655440000"

Response

200 - application/json

tokenized

token_id
string

The reusable token, or null on failure. Charge it through POST /api/transaction/charge-card, passing it as data.token.

Example:

"YGPA8MAIHEUPRM9HSJ1S1111"

error_code
string

Null on success. On failure, one of the eleven codes below — an agent reading this response should branch on the code, never on the message. Every one of them is returned with HTTP 200, because Telnyx discards the body of any other status.

Card refusals — the caller can act on these; ask for another card or re-read the one they have:
invalid_card_number — The card number is not valid.
invalid_expiry — The card expiry date is not valid.
expired_card — The card has expired.
invalid_security_code — The card security code is not valid.
invalid_postal_code — The postal code is not valid.
card_declined — The card was declined.

Try again later:
processor_unavailable — The card could not be verified right now. Please try again shortly.

Setup problems — nobody on the call can act on these; they need the connector or the merchant account fixed:
method_not_supported — This connector only supports tokenize.
payment_method_not_supported — This connector only supports card payments.
merchant_not_found — The merchant could not be identified.
merchant_unavailable — This merchant cannot accept card payments right now.

Example:

null

error_message
string

Null on success; a sentence safe to speak to the caller on failure.

Example:

null