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.
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);
}
}require "telnyx"
telnyx = Telnyx::Client.new(api_key: "My API Key")
response = telnyx.machine_payments.account_credit(amount_usd: "10.00")
puts(response)<?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();
}telnyx machine-payments account-credit \
--api-key 'My API Key' \
--amount-usd 10.00curl --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
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
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.
"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.
An account-credit transaction settled through the Machine Payment Protocol.
Show child attributes
Show child attributes
Was this page helpful?
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);
}
}require "telnyx"
telnyx = Telnyx::Client.new(api_key: "My API Key")
response = telnyx.machine_payments.account_credit(amount_usd: "10.00")
puts(response)<?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();
}telnyx machine-payments account-credit \
--api-key 'My API Key' \
--amount-usd 10.00curl --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"
}
}