> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dimepayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tokenize a card typed on a phone keypad

> Telnyx Pay's generic payment connector. Configure the connector with this
URL, `bearer` auth and a Dime API token carrying
`transaction:charge-card-token`, and set `parameters.sid` to the merchant
the card belongs to. Tokenize only — a `charge` is refused, so payments
keep going through the transaction API and its idempotency, records and
webhooks.

A business failure answers **HTTP 200** with `error_code` and
`error_message` set, because Telnyx discards the body of anything else.
Either way the Pay session ends with `payment-connector-error` and the
caller cannot retry inside it — what the 200 buys is that our code and
message reach Telnyx's `call.payment.completed` webhook, so the partner
can see why and the agent can say something true. Only authentication,
the merchant allow-list and the rate limit answer outside that shape —
those are connector misconfigurations, not something the caller on the
line can act on.

**The connector's `postal_code` step must not be set to false**:
`postal_code` is required here, as on every other card path. The security
code step needs no such request — Telnyx's flow always collects it.

The connector's `config.timeout` is a default rather than a fixed 10
seconds (milliseconds, range 1–4294967295). We answer inside 8 either
way; a partner who raises it only buys us more room.



## OpenAPI

````yaml https://app.dimepayments.com/openapi.yaml post /api/telnyx/pay
openapi: 3.0.3
info:
  title: Dime Payments API Documentation
  description: >-
    A simple, basic API for managing Merchants through Dime Payments. JSON based
    REST API
  version: 1.0.0
servers:
  - url: https://app.dimepayments.com
security:
  - default: []
tags:
  - name: Merchant management
    description: ''
  - name: Transaction management
    description: >-

      APIs for managing transactions.  Depending on API KEY permissions, one
      should be able to

      charge credit cards, ACH, Google/Apple Pay wallets along with other
      functions.
  - name: Chargeback management
    description: ''
  - name: Document management
    description: ''
  - name: Addresses
    description: |-

      APIs for managing customer addresses
  - name: Customer management
    description: >-

      APIs for managing customers.  Depending on API KEY permissions, one should
      be able to

      list, create, update, and delete customers along with several other
      customer specific requests.
  - name: Deposit management
    description: ''
  - name: Endpoints
    description: ''
  - name: Held funds
    description: ''
  - name: Invoice management
    description: >-

      APIs for managing invoices. Depending on API KEY permissions, one should
      be

      able to list, create, update, delete, and send invoices, manage their line

      items, and manage recurring-invoice schedules. Every request is scoped to
      a

      single Merchant via the required `data.sid`.
  - name: Payment Method management
    description: >-

      APIs for managing payment methods associated with customers.  Depending on
      API KEY permissions, one should be able to

      list, show, create, update, and delete payment methods.
  - name: Recurring Payments management
    description: >-

      APIs for managing recurring payments.  Depending on API KEY permissions,
      one should be able to

      create, edit, pause, cancel along with other functions.
  - name: Subscription Plans management
    description: >-

      Merchant-facing API for subscription plans (recurring offerings customers

      subscribe to). The merchant is identified by `data.sid`; the token must
      carry

      the matching `subscription-plan:*` ability. Mirrors the recurring-payment
      and

      invoice API controllers.
  - name: Subscriptions management
    description: >-

      Merchant-facing API for individual customer subscriptions (enrollments in
      a

      plan). The merchant is identified by `data.sid`; the token must carry the

      matching `subscription:*` ability. Lifecycle transitions delegate to the

      {@see \App\Actions\Subscription} action classes so the matching
      `SUBSCRIPTION_*`

      webhook always fires. Mirrors the recurring-payment and subscription-plan
      API

      controllers.
  - name: Zapier
    description: >-

      APIs for use through Zapier.  Depending on API KEY permissions, one should
      be able to

      see customers and transactions data.
paths:
  /api/telnyx/pay:
    post:
      tags:
        - Endpoints
      summary: Tokenize a card typed on a phone keypad
      description: >-
        Telnyx Pay's generic payment connector. Configure the connector with
        this

        URL, `bearer` auth and a Dime API token carrying

        `transaction:charge-card-token`, and set `parameters.sid` to the
        merchant

        the card belongs to. Tokenize only — a `charge` is refused, so payments

        keep going through the transaction API and its idempotency, records and

        webhooks.


        A business failure answers **HTTP 200** with `error_code` and

        `error_message` set, because Telnyx discards the body of anything else.

        Either way the Pay session ends with `payment-connector-error` and the

        caller cannot retry inside it — what the 200 buys is that our code and

        message reach Telnyx's `call.payment.completed` webhook, so the partner

        can see why and the agent can say something true. Only authentication,

        the merchant allow-list and the rate limit answer outside that shape —

        those are connector misconfigurations, not something the caller on the

        line can act on.


        **The connector's `postal_code` step must not be set to false**:

        `postal_code` is required here, as on every other card path. The
        security

        code step needs no such request — Telnyx's flow always collects it.


        The connector's `config.timeout` is a default rather than a fixed 10

        seconds (milliseconds, range 1–4294967295). We answer inside 8 either

        way; a partner who raises it only buys us more room.
      operationId: tokenizeACardTypedOnAPhoneKeypad
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                method:
                  type: string
                  description: Must be `tokenize`.
                  example: tokenize
                transaction_id:
                  type: string
                  description: Telnyx's id for the payment session, recorded for support.
                  example: 550e8400-e29b-41d4-a716-446655440000
                cardnumber:
                  type: string
                  description: The card number.
                  example: '4111111111111111'
                cvv:
                  type: string
                  description: The card security code.
                  example: '123'
                expiry_month:
                  type: string
                  description: Two-digit month.
                  example: '08'
                expiry_year:
                  type: string
                  description: Two-digit year.
                  example: '27'
                postal_code:
                  type: string
                  description: The cardholder's ZIP, or Canadian postal code.
                  example: '30009'
                parameters:
                  type: object
                  description: Connector parameters. Must contain `sid`.
                  example:
                    sid: '1234567'
                  properties:
                    sid:
                      type: number
                      description: ID of the merchant the card belongs to.
                      example: 1234567
                  required:
                    - sid
              required:
                - method
                - cardnumber
                - cvv
                - expiry_month
                - expiry_year
                - postal_code
                - parameters
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                  - description: tokenized
                    type: object
                    example:
                      token_id: YGPA8MAIHEUPRM9HSJ1S1111
                      error_code: null
                      error_message: null
                    properties:
                      token_id:
                        type: string
                        example: YGPA8MAIHEUPRM9HSJ1S1111
                        description: >-
                          The reusable token, or null on failure. Charge it
                          through `POST /api/transaction/charge-card`, passing
                          it as `data.token`.
                      error_code:
                        type: string
                        example: null
                        description: >-
                          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.<br><br><b>Card refusals —
                          the caller can act on these; ask for another card or
                          re-read the one they
                          have:</b><br>`invalid_card_number` — The card number
                          is not valid.<br>`invalid_expiry` — The card expiry
                          date is not valid.<br>`expired_card` — The card has
                          expired.<br>`invalid_security_code` — The card
                          security code is not valid.<br>`invalid_postal_code` —
                          The postal code is not valid.<br>`card_declined` — The
                          card was declined.<br><br><b>Try again
                          later:</b><br>`processor_unavailable` — The card could
                          not be verified right now. Please try again
                          shortly.<br><br><b>Setup problems — nobody on the call
                          can act on these; they need the connector or the
                          merchant account fixed:</b><br>`method_not_supported`
                          — This connector only supports
                          tokenize.<br>`payment_method_not_supported` — This
                          connector only supports card
                          payments.<br>`merchant_not_found` — The merchant could
                          not be identified.<br>`merchant_unavailable` — This
                          merchant cannot accept card payments right now.
                      error_message:
                        type: string
                        example: null
                        description: >-
                          Null on success; a sentence safe to speak to the
                          caller on failure.
                  - description: declined
                    type: object
                    example:
                      token_id: null
                      error_code: card_declined
                      error_message: The card was declined.
                    properties:
                      token_id:
                        type: string
                        example: null
                        description: >-
                          The reusable token, or null on failure. Charge it
                          through `POST /api/transaction/charge-card`, passing
                          it as `data.token`.
                      error_code:
                        type: string
                        example: card_declined
                        description: >-
                          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.<br><br><b>Card refusals —
                          the caller can act on these; ask for another card or
                          re-read the one they
                          have:</b><br>`invalid_card_number` — The card number
                          is not valid.<br>`invalid_expiry` — The card expiry
                          date is not valid.<br>`expired_card` — The card has
                          expired.<br>`invalid_security_code` — The card
                          security code is not valid.<br>`invalid_postal_code` —
                          The postal code is not valid.<br>`card_declined` — The
                          card was declined.<br><br><b>Try again
                          later:</b><br>`processor_unavailable` — The card could
                          not be verified right now. Please try again
                          shortly.<br><br><b>Setup problems — nobody on the call
                          can act on these; they need the connector or the
                          merchant account fixed:</b><br>`method_not_supported`
                          — This connector only supports
                          tokenize.<br>`payment_method_not_supported` — This
                          connector only supports card
                          payments.<br>`merchant_not_found` — The merchant could
                          not be identified.<br>`merchant_unavailable` — This
                          merchant cannot accept card payments right now.
                      error_message:
                        type: string
                        example: The card was declined.
                        description: >-
                          Null on success; a sentence safe to speak to the
                          caller on failure.
components:
  securitySchemes:
    default:
      type: http
      scheme: bearer
      description: >-
        You can retrieve your token by visiting your dashboard and clicking
        <b>Generate API token under your profile in top right</b>.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.