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

# Send a pay link

> Text the caller a pay link for an open Checkout Session. Repeat sends inside a short window return the link with `sent: false` rather than texting twice.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/send_link
openapi: 3.1.0
info:
  title: Ringup API
  version: v1
  description: >-
    Take a card payment on a phone call. Every endpoint is authenticated with a
    Bearer API key; the key prefix (`rk_test_` / `rk_live_`) selects the
    environment.
servers:
  - url: https://api.ringup.dev
security: []
paths:
  /v1/send_link:
    post:
      summary: Send a pay link
      description: >-
        Text the caller a pay link for an open Checkout Session. Repeat sends
        inside a short window return the link with `sent: false` rather than
        texting twice.
      operationId: sendLink
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendLinkRequest'
            example:
              checkout_session_id: cs_test_453b5401286d0f80
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendLinkResponse'
              example:
                sent: true
                pay_url: https://ringup.dev/pay/link/?t=eyJhbGciOi...
                short_url: https://ringup.dev/l/k7m2xq
                payment_required: required
                checkout_session_id: cs_test_453b5401286d0f80
                merchant_id: mch_4f2c9a1b7e3d
                order_id: 8QK4M2XJ
                platform_call_id: call_7c2a91e4
        '400':
          description: |-
            `invalid_json` The request body is not valid JSON.

            `missing_required_fields` A required parameter is missing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
              examples:
                invalid_json:
                  summary: The request body is not valid JSON.
                  value:
                    error:
                      type: invalid_request_error
                      code: invalid_json
                      audience: developer
                      message: The request body is not valid JSON.
                      advice_code: do_not_try_again
                      agent_message: null
                      display_message: null
                      agent_action: null
                      doc_url: >-
                        https://docs.ringup.dev/api-reference/error-codes#invalid_json
                      request_id: req_8f3c1d2ab4e9
                missing_required_fields:
                  summary: A required parameter is missing.
                  value:
                    error:
                      type: invalid_request_error
                      code: missing_required_fields
                      audience: developer
                      message: A required parameter is missing.
                      param: checkout_session_id
                      advice_code: do_not_try_again
                      agent_message: null
                      display_message: null
                      agent_action: null
                      doc_url: >-
                        https://docs.ringup.dev/api-reference/error-codes#missing_required_fields
                      request_id: req_8f3c1d2ab4e9
        '401':
          description: >-
            `invalid_key` The API key is missing, malformed, revoked, or does
            not match the mode of the resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
              examples:
                invalid_key:
                  summary: >-
                    The API key is missing, malformed, revoked, or does not
                    match the mode of the resource.
                  value:
                    error:
                      type: authentication_error
                      code: invalid_key
                      audience: developer
                      message: >-
                        The API key is missing, malformed, revoked, or does not
                        match the mode of the resource.
                      advice_code: do_not_try_again
                      agent_message: null
                      display_message: null
                      agent_action: null
                      doc_url: >-
                        https://docs.ringup.dev/api-reference/error-codes#invalid_key
                      request_id: req_8f3c1d2ab4e9
        '404':
          description: >-
            `session_not_found` No checkout session with that id belongs to your
            account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
              examples:
                session_not_found:
                  summary: No checkout session with that id belongs to your account.
                  value:
                    error:
                      type: invalid_request_error
                      code: session_not_found
                      audience: developer
                      message: >-
                        No checkout session with that id belongs to your
                        account.
                      advice_code: do_not_try_again
                      agent_message: null
                      display_message: null
                      agent_action: null
                      doc_url: >-
                        https://docs.ringup.dev/api-reference/error-codes#session_not_found
                      request_id: req_8f3c1d2ab4e9
        '503':
          description: >-
            `not_configured` A required backend dependency is not configured in
            this environment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
              examples:
                not_configured:
                  summary: >-
                    A required backend dependency is not configured in this
                    environment.
                  value:
                    error:
                      type: api_error
                      code: not_configured
                      audience: caller
                      message: >-
                        A required backend dependency is not configured in this
                        environment.
                      advice_code: try_again_later
                      agent_message: >-
                        I'm having trouble taking payment right now. Let me get
                        someone to help you.
                      display_message: >-
                        I'm having trouble taking payment right now. Let me get
                        someone to help you.
                      agent_action: null
                      doc_url: >-
                        https://docs.ringup.dev/api-reference/error-codes#not_configured
                      request_id: req_8f3c1d2ab4e9
      security:
        - bearerAuth: []
components:
  schemas:
    SendLinkRequest:
      additionalProperties: false
      properties:
        checkout_session_id:
          description: >-
            The only input. Caller, merchant, amount and verdict all come from
            the session, so a link can never carry a total nobody derived from
            an order.
          type: string
      required:
        - checkout_session_id
      type: object
    SendLinkResponse:
      additionalProperties: false
      properties:
        checkout_session_id:
          type: string
        merchant_id:
          type: string
        order_id:
          type:
            - string
            - 'null'
        pay_url:
          type: string
        payment_required:
          $ref: '#/components/schemas/PaymentRequired'
        platform_call_id:
          type:
            - string
            - 'null'
        sent:
          description: >-
            False when a repeat send inside the dedupe window returned a link
            WITHOUT texting. Without this a retrying agent tells the caller
            "I've texted you" when nothing went out.
          type: boolean
        short_url:
          type: string
      type: object
    ApiErrorBody:
      additionalProperties: false
      description: >-
        THE error object. Identical on every endpoint: provisioning, identify,
        checkout, cards, charge. A failed charge (which arrives as a 200 with
        `status: "failed"`) carries the SAME fields under `failure`, so a
        developer writes one parser and it works everywhere.
      properties:
        error:
          additionalProperties: false
          properties:
            advice_code:
              $ref: '#/components/schemas/AdviceCode'
              description: try_again_later | confirm_card_data | do_not_try_again
            agent_action:
              anyOf:
                - $ref: '#/components/schemas/AgentAction'
                - type: 'null'
              description: 'Null on every `developer`-audience error: see agent_message.'
            agent_message:
              description: >-
                Speak verbatim WHEN NON-NULL. Null on every `developer`-audience
                error.
              type:
                - string
                - 'null'
            audience:
              $ref: '#/components/schemas/Audience'
              description: >-
                Who this error is for. Drives whether there is anything to speak
                at all.
            charge:
              description: Present when the error concerns a specific charge.
              type: string
            code:
              $ref: '#/components/schemas/ErrorCode'
            decline_code:
              type: string
            display_message:
              description: >-
                The same fact written for a screen. Null on `developer`-audience
                errors.
              type:
                - string
                - 'null'
            doc_url:
              type: string
            message:
              type: string
            param:
              type: string
            processor_code:
              type: string
            request_id:
              type: string
            request_log_url:
              description: >-
                Deep link to this request in the dashboard. Present once the
                dashboard log view exists.
              type: string
            type:
              $ref: '#/components/schemas/ErrorType'
          type: object
      type: object
    PaymentRequired:
      enum:
        - required
        - optional
        - none
      type: string
    AdviceCode:
      description: >-
        `advice_code` is our guidance to the developer on what to do with this
        decline programmatically. It is distinct from `agent_action`, which
        drives the conversation. A decline can be "do not retry this card"
        (advice) while still being "offer a different card" (agent action).
      enum:
        - try_again_later
        - do_not_try_again
        - confirm_card_data
      type: string
    AgentAction:
      description: >-
        What the agent should DO next. Keeps conversational branching
        deterministic too.
      enum:
        - retry_card
        - offer_different_card
        - send_link
        - end_call
        - escalate
      type: string
    Audience:
      description: >-
        Who an error is for.


        `caller` errors are things the person on the phone is living through, so
        they carry copy your agent can speak. `developer` errors are your
        integration's own bugs, and carry NO speakable copy at all: the fields
        are null rather than a neutral filler, because a filler sentence invites
        an agent to raise payment when nothing about payment has failed.
      enum:
        - developer
        - caller
      type: string
    ErrorCode:
      enum:
        - invalid_json
        - missing_required_fields
        - invalid_value
        - invalid_key
        - vendor_not_provisioned
        - merchant_not_found
        - merchant_not_connected
        - invalid_processor
        - invalid_credentials
        - invalid_payment_policy
        - invalid_payment_policy_amount_cents
        - session_not_found
        - session_expired
        - session_create_failed
        - session_missing_consumer
        - missing_checkout_session_id
        - order_lookup_failed
        - order_lookup_unsupported
        - instrument_not_found
        - instrument_not_authorized
        - missing_instrument_fields
        - processor_mismatch
        - needs_enrollment
        - charge_details_mismatch
        - card_save_failed
        - card_declined
        - processor_unavailable
        - merchant_credentials_invalid
        - invalid_vault
        - key_not_found
        - invalid_environment
        - invalid_url
        - invalid_events
        - invalid_ttl
        - invalid_state_key
        - not_found
        - not_configured
        - rate_limit
        - internal_error
      type: string
    ErrorType:
      enum:
        - invalid_request_error
        - authentication_error
        - permission_error
        - card_error
        - processor_error
        - idempotency_error
        - rate_limit_error
        - api_error
      type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: rk_live_…

````