curl --request POST \
--url https://app.dimepayments.com/api/telnyx/pay \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"method": "tokenize",
"cardnumber": "4111111111111111",
"cvv": "123",
"expiry_month": "08",
"expiry_year": "27",
"postal_code": "30009",
"parameters": {
"sid": "1234567"
},
"transaction_id": "550e8400-e29b-41d4-a716-446655440000"
}
'import requests
url = "https://app.dimepayments.com/api/telnyx/pay"
payload = {
"method": "tokenize",
"cardnumber": "4111111111111111",
"cvv": "123",
"expiry_month": "08",
"expiry_year": "27",
"postal_code": "30009",
"parameters": { "sid": "1234567" },
"transaction_id": "550e8400-e29b-41d4-a716-446655440000"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
method: 'tokenize',
cardnumber: '4111111111111111',
cvv: '123',
expiry_month: '08',
expiry_year: '27',
postal_code: '30009',
parameters: {sid: '1234567'},
transaction_id: '550e8400-e29b-41d4-a716-446655440000'
})
};
fetch('https://app.dimepayments.com/api/telnyx/pay', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.dimepayments.com/api/telnyx/pay",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'method' => 'tokenize',
'cardnumber' => '4111111111111111',
'cvv' => '123',
'expiry_month' => '08',
'expiry_year' => '27',
'postal_code' => '30009',
'parameters' => [
'sid' => '1234567'
],
'transaction_id' => '550e8400-e29b-41d4-a716-446655440000'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.dimepayments.com/api/telnyx/pay"
payload := strings.NewReader("{\n \"method\": \"tokenize\",\n \"cardnumber\": \"4111111111111111\",\n \"cvv\": \"123\",\n \"expiry_month\": \"08\",\n \"expiry_year\": \"27\",\n \"postal_code\": \"30009\",\n \"parameters\": {\n \"sid\": \"1234567\"\n },\n \"transaction_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://app.dimepayments.com/api/telnyx/pay")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"method\": \"tokenize\",\n \"cardnumber\": \"4111111111111111\",\n \"cvv\": \"123\",\n \"expiry_month\": \"08\",\n \"expiry_year\": \"27\",\n \"postal_code\": \"30009\",\n \"parameters\": {\n \"sid\": \"1234567\"\n },\n \"transaction_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.dimepayments.com/api/telnyx/pay")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"method\": \"tokenize\",\n \"cardnumber\": \"4111111111111111\",\n \"cvv\": \"123\",\n \"expiry_month\": \"08\",\n \"expiry_year\": \"27\",\n \"postal_code\": \"30009\",\n \"parameters\": {\n \"sid\": \"1234567\"\n },\n \"transaction_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n}"
response = http.request(request)
puts response.read_body{
"token_id": "YGPA8MAIHEUPRM9HSJ1S1111",
"error_code": null,
"error_message": null
}Tokenize a card typed on a phone keypad
Telnyx Pay’s generic payment connector. Configure the connector with this
URL, bearer auth and a Dime API token carrying
transaction:charge-card-token, and set parameters.sid to the merchant
the card belongs to. Tokenize only — a charge is refused, so payments
keep going through the transaction API and its idempotency, records and
webhooks.
A business failure answers HTTP 200 with error_code and
error_message set, because Telnyx discards the body of anything else.
Either way the Pay session ends with payment-connector-error and the
caller cannot retry inside it — what the 200 buys is that our code and
message reach Telnyx’s call.payment.completed webhook, so the partner
can see why and the agent can say something true. Only authentication,
the merchant allow-list and the rate limit answer outside that shape —
those are connector misconfigurations, not something the caller on the
line can act on.
The connector’s postal_code step must not be set to false:
postal_code is required here, as on every other card path. The security
code step needs no such request — Telnyx’s flow always collects it.
The connector’s config.timeout is a default rather than a fixed 10
seconds (milliseconds, range 1–4294967295). We answer inside 8 either
way; a partner who raises it only buys us more room.
curl --request POST \
--url https://app.dimepayments.com/api/telnyx/pay \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"method": "tokenize",
"cardnumber": "4111111111111111",
"cvv": "123",
"expiry_month": "08",
"expiry_year": "27",
"postal_code": "30009",
"parameters": {
"sid": "1234567"
},
"transaction_id": "550e8400-e29b-41d4-a716-446655440000"
}
'import requests
url = "https://app.dimepayments.com/api/telnyx/pay"
payload = {
"method": "tokenize",
"cardnumber": "4111111111111111",
"cvv": "123",
"expiry_month": "08",
"expiry_year": "27",
"postal_code": "30009",
"parameters": { "sid": "1234567" },
"transaction_id": "550e8400-e29b-41d4-a716-446655440000"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
method: 'tokenize',
cardnumber: '4111111111111111',
cvv: '123',
expiry_month: '08',
expiry_year: '27',
postal_code: '30009',
parameters: {sid: '1234567'},
transaction_id: '550e8400-e29b-41d4-a716-446655440000'
})
};
fetch('https://app.dimepayments.com/api/telnyx/pay', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.dimepayments.com/api/telnyx/pay",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'method' => 'tokenize',
'cardnumber' => '4111111111111111',
'cvv' => '123',
'expiry_month' => '08',
'expiry_year' => '27',
'postal_code' => '30009',
'parameters' => [
'sid' => '1234567'
],
'transaction_id' => '550e8400-e29b-41d4-a716-446655440000'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.dimepayments.com/api/telnyx/pay"
payload := strings.NewReader("{\n \"method\": \"tokenize\",\n \"cardnumber\": \"4111111111111111\",\n \"cvv\": \"123\",\n \"expiry_month\": \"08\",\n \"expiry_year\": \"27\",\n \"postal_code\": \"30009\",\n \"parameters\": {\n \"sid\": \"1234567\"\n },\n \"transaction_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://app.dimepayments.com/api/telnyx/pay")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"method\": \"tokenize\",\n \"cardnumber\": \"4111111111111111\",\n \"cvv\": \"123\",\n \"expiry_month\": \"08\",\n \"expiry_year\": \"27\",\n \"postal_code\": \"30009\",\n \"parameters\": {\n \"sid\": \"1234567\"\n },\n \"transaction_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.dimepayments.com/api/telnyx/pay")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"method\": \"tokenize\",\n \"cardnumber\": \"4111111111111111\",\n \"cvv\": \"123\",\n \"expiry_month\": \"08\",\n \"expiry_year\": \"27\",\n \"postal_code\": \"30009\",\n \"parameters\": {\n \"sid\": \"1234567\"\n },\n \"transaction_id\": \"550e8400-e29b-41d4-a716-446655440000\"\n}"
response = http.request(request)
puts response.read_body{
"token_id": "YGPA8MAIHEUPRM9HSJ1S1111",
"error_code": null,
"error_message": null
}Authorizations
Body
Response
- Option 1
- Option 2
tokenized
Null on success. On failure, one of the eleven codes below — an agent reading this response should branch on the code, never on the message. Every one of them is returned with HTTP 200, because Telnyx discards the body of any other status.
Card refusals — the caller can act on these; ask for another card or re-read the one they have:invalid_card_number — The card number is not valid.invalid_expiry — The card expiry date is not valid.expired_card — The card has expired.invalid_security_code — The card security code is not valid.invalid_postal_code — The postal code is not valid.card_declined — The card was declined.
Try again later:processor_unavailable — The card could not be verified right now. Please try again shortly.
Setup problems — nobody on the call can act on these; they need the connector or the merchant account fixed:method_not_supported — This connector only supports tokenize.payment_method_not_supported — This connector only supports card payments.merchant_not_found — The merchant could not be identified.merchant_unavailable — This merchant cannot accept card payments right now.
null

