Create a machine payment 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.

POST

machine-payments

account-credit

JavaScript

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});

const response = await client.machinePayments.accountCredit({
  amount_usd: '10.00',
});

console.log(response.data);

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),  # This is the default and can be omitted
)
response = client.machine_payments.account_credit(
    amount_usd="10.00",
)
print(response.data)

package main

import (
	"context"
	"fmt"

	"github.com/team-telnyx/telnyx-go"
	"github.com/team-telnyx/telnyx-go/option"
)

func main() {
	client := telnyx.NewClient(
		option.WithAPIKey("My API Key"),
	)
	response, err := client.MachinePayments.AccountCredit(
		context.TODO(),
		telnyx.MachinePaymentAccountCreditParams{
			AmountUsd: "10.00",
		},
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", response.Data)
}

package com.telnyx.sdk.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.machinePayments.MachinePaymentAccountCreditParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        MachinePaymentAccountCreditParams params = MachinePaymentAccountCreditParams.builder()
            .amountUsd("10.00")
            .build();
        var response = client.machinePayments().accountCredit(params);
    }
}

<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

use Telnyx\Client;
use Telnyx\Core\Exceptions\APIException;

$client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API Key');

try {
  $response = $client->machinePayments->accountCredit(
    amount_usd: '10.00',
  );

  var_dump($response);
} catch (APIException $e) {
  echo $e->getMessage();
}

curl --request POST \
  --url https://api.telnyx.com/v2/machine-payments/account-credit \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount_usd": "10.00"
}
'

{
  "data": {
    "id": "de06811a-2e43-4561-af5a-7d0a26e20bbb",
    "record_type": "machine_payment_account_credit",
    "account_id": "123456789",
    "amount": "10.00",
    "currency": "USD",
    "payment_source": "machine_payment",
    "provider": "stripe",
    "payment_method": "stripe_spt",
    "payment_intent_id": "pi_3OrJx2eZvKYlo2C1234abcd",
    "receipt_reference": "pi_3OrJx2eZvKYlo2C1234abcd",
    "mpp_resource": "telnyx:account-credit:123456789:usd:10.00",
    "status": "settled",
    "created": false,
    "created_at": "2026-08-12T15:00:00Z"
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

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.

Example:

"10.00"

Response

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.

data

object

An account-credit transaction settled through the Machine Payment Protocol.

Show child attributes

JavaScript

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});

const response = await client.machinePayments.accountCredit({
  amount_usd: '10.00',
});

console.log(response.data);

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),  # This is the default and can be omitted
)
response = client.machine_payments.account_credit(
    amount_usd="10.00",
)
print(response.data)

package main

import (
	"context"
	"fmt"

	"github.com/team-telnyx/telnyx-go"
	"github.com/team-telnyx/telnyx-go/option"
)

func main() {
	client := telnyx.NewClient(
		option.WithAPIKey("My API Key"),
	)
	response, err := client.MachinePayments.AccountCredit(
		context.TODO(),
		telnyx.MachinePaymentAccountCreditParams{
			AmountUsd: "10.00",
		},
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", response.Data)
}

package com.telnyx.sdk.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.machinePayments.MachinePaymentAccountCreditParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        MachinePaymentAccountCreditParams params = MachinePaymentAccountCreditParams.builder()
            .amountUsd("10.00")
            .build();
        var response = client.machinePayments().accountCredit(params);
    }
}

<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

use Telnyx\Client;
use Telnyx\Core\Exceptions\APIException;

$client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API Key');

try {
  $response = $client->machinePayments->accountCredit(
    amount_usd: '10.00',
  );

  var_dump($response);
} catch (APIException $e) {
  echo $e->getMessage();
}

curl --request POST \
  --url https://api.telnyx.com/v2/machine-payments/account-credit \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount_usd": "10.00"
}
'

{
  "data": {
    "id": "de06811a-2e43-4561-af5a-7d0a26e20bbb",
    "record_type": "machine_payment_account_credit",
    "account_id": "123456789",
    "amount": "10.00",
    "currency": "USD",
    "payment_source": "machine_payment",
    "provider": "stripe",
    "payment_method": "stripe_spt",
    "payment_intent_id": "pi_3OrJx2eZvKYlo2C1234abcd",
    "receipt_reference": "pi_3OrJx2eZvKYlo2C1234abcd",
    "mpp_resource": "telnyx:account-credit:123456789:usd:10.00",
    "status": "settled",
    "created": false,
    "created_at": "2026-08-12T15:00:00Z"
  }
}

Account & Billing

Video

SETI

Fax

OAuth

Bot Signup

For AI Agents

Create a machine payment account credit

Authorizations

Body

Response