--- title: "Create a machine payment account credit" method: POST path: "/machine-payments/account-credit" tags: ["Machine Payments"] --- # Create a machine payment account credit `POST /machine-payments/account-credit` Creates an account credit using the Machine Payment Protocol (MPP), an HTTP-402 payment flow for machines and agents. The flow has two steps. First, send an authenticated request with the `amount_usd` to credit; the response is `402 Payment Required` with one or more payment challenges (for example separate Tempo and Stripe challenges) in the `WWW-Authenticate` header. Second, retry the request with an `Authorization: Payment ...` credential constructed from the challenge; on success the response includes the credited transaction and a `Payment-Receipt` header. The credited account is never chosen by the request body: the initial request credits the account of the authenticated user, and a paid retry credits the account bound to the verified payment credential. The amount must be within the configured bounds (by default between 5.00 and 500.00 USD). Successful paid retries are idempotent — when Rails reaches its duplicate-transaction lookup for an already-recorded payment, it returns the existing transaction with `created: false` instead of crediting the account again. This deduplication applies to successful fulfillment: re-sending the same Stripe credential may instead be rejected by the upstream provider as an idempotent replay and return `402 Payment Required` rather than the existing transaction. > **Warning: the payment credential is bound to a specific Telnyx account ID.** A payment is captured before the bound account is validated. If the credential names an account that is missing, suspended, blocked, cancelled, dormant, or ineligible for the tier, the payment is captured but **no account is credited**. If the credential names a different but eligible account, that account is credited — the service does not compare it against the payer's account. There is **no automatic refund**: if the captured payment does not credit the intended account, contact Telnyx support for remediation. ## Request body - MachinePaymentAccountCreditRequest - `amount_usd` string, required — Amount to credit in USD, as a decimal string with up to two fractional digits (by default between 5.00 and 500.00). The request body is required on the initial challenge request and remains required on a paid retry, where you re-send the identical body plus the payment credential — the credential, not the body, selects the payment, and the retried body is not re-validated. ## Response `200` Successful duplicate paid retry — the existing account-credit transaction is returned and the account is not credited again. This applies when Rails reaches its duplicate-transaction lookup; re-sending the same Stripe credential may instead be rejected by the upstream provider as an idempotent replay and return `402 Payment Required`. - MachinePaymentAccountCreditResponse - `data` MachinePaymentAccountCredit — An account-credit transaction settled through the Machine Payment Protocol. - `id` string, required — Unique identifier of the account-credit transaction. - `record_type` 'machine_payment_account_credit', required — Record type identifier. - `account_id` string, required — Identifier of the credited Telnyx account. Derived from the authenticated user on the initial request and from the verified payment credential on a paid retry — never from the request body. - `amount` string, required — Credited amount as a decimal string with two fractional digits. - `currency` string, required — ISO 4217 currency code of the credited amount (currently always USD). - `payment_source` 'machine_payment', required — Payment source identifier distinguishing machine payments from other account-credit sources. - `provider` 'stripe' | 'tempo' | 'null', nullable — Upstream payment provider that settled the payment. - `payment_method` 'stripe_spt' | 'tempo_usdc' | 'null', nullable — Payment method used by the provider: `stripe_spt` for Stripe Shared Payment Token payments, `tempo_usdc` for Tempo USDC payments. - `payment_intent_id` string, nullable — Stripe PaymentIntent identifier for Stripe settlements. Absent for Tempo settlements. - `receipt_reference` string, nullable — Provider receipt reference: the Stripe PaymentIntent identifier for Stripe settlements, or the on-chain transaction hash for Tempo settlements. - `mpp_resource` string, nullable — Machine Payment Protocol resource identifier the payment credential was bound to. - `status` 'new' | 'processing' | 'settled' | 'expired' | 'invalid' | 'null', nullable — Status of the transaction. Successful machine payment credits are recorded as `settled`. - `created` boolean — True when this response created a new account credit, false when an existing transaction was returned for a duplicate paid retry. - `created_at` string, date-time — ISO 8601 timestamp when the transaction was created. ## Other responses - `201` — Account credit created from a verified machine payment - `400` — Bad request — proxied verbatim from the upstream machine payment service when it rejects the request: a malformed or undeserializable `Authorization: Payment ...` credential, a payment credential whose amount violates the upstream amount policy, or a request that fails upstream schema validation. The body is the upstream singular `error` envelope, not the standard Telnyx `errors` array. - `401` — Unauthorized — the request carried neither valid Telnyx API credentials nor an `Authorization: Payment ...` credential - `402` — Payment required. One or more Machine Payment Protocol challenges (for example separate Tempo and Stripe challenges) are returned in the `WWW-Authenticate` header. Construct a payment credential from a challenge and retry the request with an `Authorization: Payment ...` header. - `403` — Forbidden — machine payments are not enabled for the account, the account tier is ineligible, the account is suspended, or the request origin is not permitted. Note: when the account is suspended the failure is returned via `render_failure` as `{"success": false, "message": "You must verify your identity before you may perform this action.", "reasons": []}` rather than the standard `errors` envelope. - `404` — Not found — proxied verbatim from the upstream machine payment service when the machine payment provider is disabled. The body is the upstream singular `error` envelope, not the standard Telnyx `errors` array. - `409` — Conflict — the payment maps to an already-recorded account credit with different fulfillment metadata, so the account is not credited again - `422` — Unprocessable entity — missing or invalid `amount_usd`, or the request fails account-credit policy checks - `502` — Bad gateway — the upstream machine payment service failed to process the request. Other upstream failure statuses (for example 404 when the machine payment provider is disabled, or 400 for schema validation failures) may be proxied verbatim to the client. ## Changes > 99 revisions in range; 1 not diffed. - **2026-09-23** `ac329fbabc9d` — 1 info - endpoint added [Change history](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/changes/machine-payments/account-credit/post.md) --- [API](https://skmtc.dev/team-telnyx/apis/telnyx-api-2.md) · [All operations](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/llms.txt) · [OpenAPI document](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/revisions/227c33b1ac9c?raw)