/telnyx-acp-payment

name: telnyx-acp-payment
description: >-
  Add credit to a Telnyx account through an Agentic Commerce Protocol (ACP)
  checkout, paying with a Stripe Link agent wallet or Tempo USDC, then verify
  the order and balance.
metadata:
  author: telnyx
  product: payments
  requires:
    bins:
      - curl
      - jq
      - node
      - npm
      - npx
    env:
      - TELNYX_API_KEY

Pay into your Telnyx account with ACP

Use Agentic Commerce Protocol (ACP) to add USD credit to your Telnyx account. You create a checkout, pay it with a Stripe Link agent wallet backed by an eligible card or with USDC from a funded Tempo wallet, and complete the checkout once. Telnyx credits the account that owns the API key.

When to use this skill

Use this skill when you want an ACP checkout lifecycle around a Telnyx account-credit payment: a checkout you can retrieve, cancel, and reconcile, with idempotency keys on every write and an order record when it completes. If you only want the single-request HTTP `402` flow, the `telnyx-mpp-payment` skill funds the same account with the same Link or Tempo credentials.

All Telnyx ACP account-credit checkouts use these endpoints:

POST https://api.telnyx.com/v2/checkout_sessions
GET  https://api.telnyx.com/v2/checkout_sessions/{checkout_id}
POST https://api.telnyx.com/v2/checkout_sessions/{checkout_id}/complete
POST https://api.telnyx.com/v2/checkout_sessions/{checkout_id}/cancel

There is one product: USD account credit, catalog item `account_credit_usd`. Each checkout advertises the payment handlers it accepts. Telnyx uses Machine Payment Protocol (MPP) challenges inside those handlers, so the Link and Tempo payment steps are the same ones used for a direct MPP payment.

Before you pay

• These payments move real funds. Check the amount, payment method, and Telnyx account before you approve anything.
• Use an API key for the account you want to credit. Telnyx gets the account from your API key. Do not send `account_id`.
• Write the amount in whole US cents as an integer, such as `1200` for `$12.00`.
• Per-payment amount limits apply and may change. An amount outside them is rejected with a generic `400 invalid_request` that does not state the limits; if a well-formed create request gets that error, try a smaller amount or contact Telnyx Support.
• Send `API-Version: 2026-04-17` on every request. Other versions are rejected.
• Generate and save one `Idempotency-Key` per logical operation (create, complete, cancel) before you start. Re-use that key if you have to re-send the same request after a network failure; never mint a new key per attempt, and never use a new key to get past a conflict.
• A checkout expires. Check `expires_at` and start a new checkout if it has passed. Checkouts cannot be updated; create a new one instead.
• The payment is tied to the account and amount in the checkout's challenge. Do not change either after you approve or sign it.
• Complete a checkout exactly once. Never reuse a Link spend request, Shared Payment Token, Tempo payment credential, or completed challenge.
• Link accepts eligible cards in supported regions — currently cards issued in the United States or Canada.
• Never print, commit, or send your API key, Link access token, Shared Payment Token, wallet private key, or a signed `Payment ...` credential.

Setup

You need `curl`, `jq`, Node.js, npm, and a Telnyx API key. Link payments use `@stripe/link-cli@0.16.0`. Tempo payments use `mppx@0.6.28` and a funded Tempo wallet. Both tools run through `npx`, so nothing is installed into your project.

Run every command block below in the same shell session. Later blocks reuse variables such as `CHECKOUT` and `ACP_CHECKOUT_ID` that earlier blocks set.

Environment variables

| Variable | Required | Description | |---|---|---| | `TELNYX_API_KEY` | Yes | API key for the Telnyx account that will receive the credit | | `ACP_AMOUNT_CENTS` | Yes | Positive integer amount in US cents | | `ACP_BASE_URL` | Yes | `https://api.telnyx.com` | | `ACP_CREATE_KEY`, `ACP_COMPLETE_KEY`, `ACP_CANCEL_KEY` | Yes | One `Idempotency-Key` per logical operation, generated up front and kept for support | | `ACP_CHECKOUT_ID` | After create | Checkout `id` returned by the create request | | `LINK_PAYMENT_METHOD_ID` | Link only | Eligible Link card payment-method ID | | `LINK_NETWORK_ID` | Link only | `config.merchant_id` from the checkout's Stripe handler | | `LINK_SPEND_REQUEST_ID` | Link only | Approved, one-time Link spend-request ID |

Keep the API key in your shell environment rather than putting it directly in a command or file:

export TELNYX_API_KEY='KEYxxxxx'
export ACP_AMOUNT_CENTS='1200'
export ACP_BASE_URL='https://api.telnyx.com'
export ACP_CREATE_KEY="$(node -e 'console.log(crypto.randomUUID())')"
export ACP_COMPLETE_KEY="$(node -e 'console.log(crypto.randomUUID())')"
export ACP_CANCEL_KEY="$(node -e 'console.log(crypto.randomUUID())')"
echo "create=$ACP_CREATE_KEY complete=$ACP_COMPLETE_KEY cancel=$ACP_CANCEL_KEY"

Record the three keys now. Support can trace an operation by its key, and the same key is what you re-send if a request is interrupted.

Read your starting balance

curl -sS "$ACP_BASE_URL/v2/balance" \
  -H "Authorization: Bearer $TELNYX_API_KEY"

Save `data.available_credit` so you can confirm the credit later.

Create the checkout

Save the response in a private temporary file because it contains the payment challenge for your account:

umask 077
CHECKOUT="$(mktemp /tmp/telnyx-acp-checkout.XXXXXX)"

curl -sS \
  --output "$CHECKOUT" \
  --write-out '%{http_code}\n' \
  -X POST "$ACP_BASE_URL/v2/checkout_sessions" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H 'API-Version: 2026-04-17' \
  -H "Idempotency-Key: $ACP_CREATE_KEY" \
  -H 'Content-Type: application/json' \
  --data "{\"line_items\":[{\"id\":\"account_credit_usd\",\"unit_amount\":$ACP_AMOUNT_CENTS}],\"currency\":\"usd\",\"capabilities\":{}}"

The res