/telnyx-mpp-payment

name: telnyx-mpp-payment
description: >-
  Add credit to a Telnyx account through Machine Payment Protocol (MPP)
  using Stripe Link or Tempo USDC, then verify the transaction and balance.
metadata:
  author: telnyx
  product: payments
  requires:
    bins:
      - curl
      - node
      - npm
      - npx
    env:
      - TELNYX_API_KEY

Pay into your Telnyx account with MPP

Use Machine Payment Protocol (MPP) to add USD credit to your Telnyx account. You can pay with a Stripe Link agent wallet backed by an eligible card, or with USDC from a funded Tempo wallet.

When to use this skill

Use this skill when you want to add Telnyx account credit through an HTTP `402 Payment Required` flow using Stripe Link or Tempo USDC. It guides you through setup, payment approval, the paid retry, status checks, and safe support handoff.

All Telnyx MPP account-credit payments use this endpoint:

https://api.telnyx.com/v2/machine-payments/account-credit

The first request returns HTTP `402 Payment Required`. This is an expected part of the payment flow. Link CLI or `mppx` reads the challenge, pays it, and retries the request with proof of payment. Telnyx credits the account that owns the API key used for the first request.

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.
• Send only `amount_usd` in the request body. Do not send `account_id`; Telnyx gets the account from your API key.
• Write the amount as a positive USD value with no more than two decimal places, such as `12.00`.
• The maximum amount payable in a single MPP transaction may vary.
• Your Telnyx account must be active and eligible for machine payments.
• The payment is tied to the account and amount in the challenge. Do not change either after you approve or sign it.
• Never reuse a Link spend request, Shared Payment Token, Tempo payment credential, or completed challenge.
• Only cards issued in the United States or Canada are currently accepted for MPP payments through Link.
• Never print, commit, or send your API key, Link access token, Shared Payment Token, wallet private key, or `Authorization: Payment` value.

Setup

You need Node.js, npm, `curl`, and a Telnyx API key. Link payments use `@stripe/link-cli@0.11.0`. Tempo payments use `mppx` and a funded Tempo wallet.

Environment variables

| Variable | Required | Description | |---|---|---| | `TELNYX_API_KEY` | Yes | API key for the Telnyx account that will receive the credit | | `MPP_AMOUNT_USD` | Yes | Positive USD amount with no more than two decimal places | | `MPP_ENDPOINT` | Yes | Telnyx MPP account-credit endpoint shown below | | `LINK_PAYMENT_METHOD_ID` | Link only | Eligible Link card payment-method ID | | `LINK_NETWORK_ID` | Link only | Network ID decoded from the current payment challenge | | `LINK_SPEND_REQUEST_ID` | Link only | Approved, one-time Link spend-request ID | | `TELNYX_TRANSACTION_ID` | Status check only | Transaction ID returned by a completed payment |

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

export TELNYX_API_KEY='KEYxxxxx'
export MPP_AMOUNT_USD='12.00'
export MPP_ENDPOINT='https://api.telnyx.com/v2/machine-payments/account-credit'

Pay with Link

Sign in

npx --yes @stripe/link-cli@0.11.0 auth login \
  --client-name 'Telnyx MPP payer' \
  --timeout 600

Open the URL shown by the CLI, confirm the phrase, and approve access. Check that the sign-in completed:

npx --yes @stripe/link-cli@0.11.0 auth status

Choose a card

npx --yes @stripe/link-cli@0.11.0 payment-methods list --format json

Choose a card marked as eligible for agentic payments. Only cards issued in the United States or Canada are currently accepted for MPP payments through Link.

export LINK_PAYMENT_METHOD_ID='<csmrpd-id>'

Get a fresh payment challenge

Save the response headers and body in private temporary files:

umask 077
CHALLENGE_HEADERS="$(mktemp /tmp/telnyx-mpp-headers.XXXXXX)"
CHALLENGE_BODY="$(mktemp /tmp/telnyx-mpp-body.XXXXXX)"

curl -sS \
  --dump-header "$CHALLENGE_HEADERS" \
  --output "$CHALLENGE_BODY" \
  --write-out '%{http_code}\n' \
  -X POST "$MPP_ENDPOINT" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H 'Content-Type: application/json' \
  --data "{\"amount_usd\":\"$MPP_AMOUNT_USD\"}"

The response should be HTTP `402`. Find the Stripe `WWW-Authenticate: Payment ...` header and decode it:

npx --yes @stripe/link-cli@0.11.0 mpp decode \
  --challenge '<complete Stripe Payment challenge header value>'

Copy `methodDetails.networkId` from the decoded challenge:

export LINK_NETWORK_ID='<networkId-from-current-challenge>'

Always use the value from the current challenge. Save the `X-Request-Id` response header as well; Telnyx Support can use it to trace this request. Keep the full challenge private because it contains the account and amount for the payment.

Create and approve the spend request

Link expects the amount in cents. Convert `MPP_AMOUNT_USD` to cents and use that integer for `--amount`.

npx --yes @stripe/link-cli@0.11.0 spend-request create \
  --payment-method-id "$LINK_PAYMENT_METHOD_ID" \
  --credential-type shared_payment_token \
  --network-id "$LINK_NETWORK_ID" \
  --amount '<amount-in-cents>' \
  --currency usd \
  --context 'Authorize one card payment to add the specified USD credit to my Telnyx account through Machine Payment Protocol using Stripe Link.' \
  --request-approval

Open the approval URL and check the card and amount before clicking **Approve**. Save the spend-request ID and retrieve it until its status is `approved`:

export LINK_SPEND_REQUEST_ID='<lsrq-id>'
npx --yes @stripe/link-cli@0.11.0 spend-request retrieve "$LINK_SPEND_REQUEST_ID"

Each spend request can be used once. Create and approve