Telephone Order - Charge
curl --request POST \
--url https://sandbox.hyperswitch.io/telephone_order/{merchant_id}/{provider} \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"amount": "1.00",
"cardnumber": "4242424242424242",
"currency_code": "USD",
"cvv": "123",
"description": "Order placed over the phone",
"expiry_month": "12",
"expiry_year": "28",
"method": "charge",
"parameters": {
"payment_id": "pay_8320b449b06630271e378214dab80ce5",
"profile_id": "pro_GUMsmmzTU7oadT00pJeo"
},
"postal_code": "94122",
"transaction_id": "IPe16430-39ba-4820-bedc-7aad0762a487"
}
'import requests
url = "https://sandbox.hyperswitch.io/telephone_order/{merchant_id}/{provider}"
payload = {
"amount": "1.00",
"cardnumber": "4242424242424242",
"currency_code": "USD",
"cvv": "123",
"description": "Order placed over the phone",
"expiry_month": "12",
"expiry_year": "28",
"method": "charge",
"parameters": {
"payment_id": "pay_8320b449b06630271e378214dab80ce5",
"profile_id": "pro_GUMsmmzTU7oadT00pJeo"
},
"postal_code": "94122",
"transaction_id": "IPe16430-39ba-4820-bedc-7aad0762a487"
}
headers = {
"Authorization": "Basic <encoded-value>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
body: JSON.stringify({
amount: '1.00',
cardnumber: '4242424242424242',
currency_code: 'USD',
cvv: '123',
description: 'Order placed over the phone',
expiry_month: '12',
expiry_year: '28',
method: 'charge',
parameters: {
payment_id: 'pay_8320b449b06630271e378214dab80ce5',
profile_id: 'pro_GUMsmmzTU7oadT00pJeo'
},
postal_code: '94122',
transaction_id: 'IPe16430-39ba-4820-bedc-7aad0762a487'
})
};
fetch('https://sandbox.hyperswitch.io/telephone_order/{merchant_id}/{provider}', 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://sandbox.hyperswitch.io/telephone_order/{merchant_id}/{provider}",
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([
'amount' => '1.00',
'cardnumber' => '4242424242424242',
'currency_code' => 'USD',
'cvv' => '123',
'description' => 'Order placed over the phone',
'expiry_month' => '12',
'expiry_year' => '28',
'method' => 'charge',
'parameters' => [
'payment_id' => 'pay_8320b449b06630271e378214dab80ce5',
'profile_id' => 'pro_GUMsmmzTU7oadT00pJeo'
],
'postal_code' => '94122',
'transaction_id' => 'IPe16430-39ba-4820-bedc-7aad0762a487'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Basic <encoded-value>",
"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://sandbox.hyperswitch.io/telephone_order/{merchant_id}/{provider}"
payload := strings.NewReader("{\n \"amount\": \"1.00\",\n \"cardnumber\": \"4242424242424242\",\n \"currency_code\": \"USD\",\n \"cvv\": \"123\",\n \"description\": \"Order placed over the phone\",\n \"expiry_month\": \"12\",\n \"expiry_year\": \"28\",\n \"method\": \"charge\",\n \"parameters\": {\n \"payment_id\": \"pay_8320b449b06630271e378214dab80ce5\",\n \"profile_id\": \"pro_GUMsmmzTU7oadT00pJeo\"\n },\n \"postal_code\": \"94122\",\n \"transaction_id\": \"IPe16430-39ba-4820-bedc-7aad0762a487\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Basic <encoded-value>")
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://sandbox.hyperswitch.io/telephone_order/{merchant_id}/{provider}")
.header("Authorization", "Basic <encoded-value>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": \"1.00\",\n \"cardnumber\": \"4242424242424242\",\n \"currency_code\": \"USD\",\n \"cvv\": \"123\",\n \"description\": \"Order placed over the phone\",\n \"expiry_month\": \"12\",\n \"expiry_year\": \"28\",\n \"method\": \"charge\",\n \"parameters\": {\n \"payment_id\": \"pay_8320b449b06630271e378214dab80ce5\",\n \"profile_id\": \"pro_GUMsmmzTU7oadT00pJeo\"\n },\n \"postal_code\": \"94122\",\n \"transaction_id\": \"IPe16430-39ba-4820-bedc-7aad0762a487\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://sandbox.hyperswitch.io/telephone_order/{merchant_id}/{provider}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"amount\": \"1.00\",\n \"cardnumber\": \"4242424242424242\",\n \"currency_code\": \"USD\",\n \"cvv\": \"123\",\n \"description\": \"Order placed over the phone\",\n \"expiry_month\": \"12\",\n \"expiry_year\": \"28\",\n \"method\": \"charge\",\n \"parameters\": {\n \"payment_id\": \"pay_8320b449b06630271e378214dab80ce5\",\n \"profile_id\": \"pro_GUMsmmzTU7oadT00pJeo\"\n },\n \"postal_code\": \"94122\",\n \"transaction_id\": \"IPe16430-39ba-4820-bedc-7aad0762a487\"\n}"
response = http.request(request)
puts response.read_body{
"charge_id": "pay_8320b449b06630271e378214dab80ce5",
"error_code": null,
"error_message": null,
"parameters": {
"amount_capturable": "0",
"amount_received": "100",
"connector": "stripe",
"connector_transaction_id": "pi_3URyI8D5R7gDAGff17RhZpfW",
"merchant_order_reference_id": "IPe16430-39ba-4820-bedc-7aad0762a487",
"payment_id": "pay_8320b449b06630271e378214dab80ce5",
"status": "succeeded"
}
}Telephone Order
Telephone Order - Charge
Charges a card that an IVR provider collected over the phone. Only twilio is supported as {provider}.
POST
/
telephone_order
/
{merchant_id}
/
{provider}
Telephone Order - Charge
curl --request POST \
--url https://sandbox.hyperswitch.io/telephone_order/{merchant_id}/{provider} \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"amount": "1.00",
"cardnumber": "4242424242424242",
"currency_code": "USD",
"cvv": "123",
"description": "Order placed over the phone",
"expiry_month": "12",
"expiry_year": "28",
"method": "charge",
"parameters": {
"payment_id": "pay_8320b449b06630271e378214dab80ce5",
"profile_id": "pro_GUMsmmzTU7oadT00pJeo"
},
"postal_code": "94122",
"transaction_id": "IPe16430-39ba-4820-bedc-7aad0762a487"
}
'import requests
url = "https://sandbox.hyperswitch.io/telephone_order/{merchant_id}/{provider}"
payload = {
"amount": "1.00",
"cardnumber": "4242424242424242",
"currency_code": "USD",
"cvv": "123",
"description": "Order placed over the phone",
"expiry_month": "12",
"expiry_year": "28",
"method": "charge",
"parameters": {
"payment_id": "pay_8320b449b06630271e378214dab80ce5",
"profile_id": "pro_GUMsmmzTU7oadT00pJeo"
},
"postal_code": "94122",
"transaction_id": "IPe16430-39ba-4820-bedc-7aad0762a487"
}
headers = {
"Authorization": "Basic <encoded-value>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
body: JSON.stringify({
amount: '1.00',
cardnumber: '4242424242424242',
currency_code: 'USD',
cvv: '123',
description: 'Order placed over the phone',
expiry_month: '12',
expiry_year: '28',
method: 'charge',
parameters: {
payment_id: 'pay_8320b449b06630271e378214dab80ce5',
profile_id: 'pro_GUMsmmzTU7oadT00pJeo'
},
postal_code: '94122',
transaction_id: 'IPe16430-39ba-4820-bedc-7aad0762a487'
})
};
fetch('https://sandbox.hyperswitch.io/telephone_order/{merchant_id}/{provider}', 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://sandbox.hyperswitch.io/telephone_order/{merchant_id}/{provider}",
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([
'amount' => '1.00',
'cardnumber' => '4242424242424242',
'currency_code' => 'USD',
'cvv' => '123',
'description' => 'Order placed over the phone',
'expiry_month' => '12',
'expiry_year' => '28',
'method' => 'charge',
'parameters' => [
'payment_id' => 'pay_8320b449b06630271e378214dab80ce5',
'profile_id' => 'pro_GUMsmmzTU7oadT00pJeo'
],
'postal_code' => '94122',
'transaction_id' => 'IPe16430-39ba-4820-bedc-7aad0762a487'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Basic <encoded-value>",
"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://sandbox.hyperswitch.io/telephone_order/{merchant_id}/{provider}"
payload := strings.NewReader("{\n \"amount\": \"1.00\",\n \"cardnumber\": \"4242424242424242\",\n \"currency_code\": \"USD\",\n \"cvv\": \"123\",\n \"description\": \"Order placed over the phone\",\n \"expiry_month\": \"12\",\n \"expiry_year\": \"28\",\n \"method\": \"charge\",\n \"parameters\": {\n \"payment_id\": \"pay_8320b449b06630271e378214dab80ce5\",\n \"profile_id\": \"pro_GUMsmmzTU7oadT00pJeo\"\n },\n \"postal_code\": \"94122\",\n \"transaction_id\": \"IPe16430-39ba-4820-bedc-7aad0762a487\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Basic <encoded-value>")
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://sandbox.hyperswitch.io/telephone_order/{merchant_id}/{provider}")
.header("Authorization", "Basic <encoded-value>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": \"1.00\",\n \"cardnumber\": \"4242424242424242\",\n \"currency_code\": \"USD\",\n \"cvv\": \"123\",\n \"description\": \"Order placed over the phone\",\n \"expiry_month\": \"12\",\n \"expiry_year\": \"28\",\n \"method\": \"charge\",\n \"parameters\": {\n \"payment_id\": \"pay_8320b449b06630271e378214dab80ce5\",\n \"profile_id\": \"pro_GUMsmmzTU7oadT00pJeo\"\n },\n \"postal_code\": \"94122\",\n \"transaction_id\": \"IPe16430-39ba-4820-bedc-7aad0762a487\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://sandbox.hyperswitch.io/telephone_order/{merchant_id}/{provider}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"amount\": \"1.00\",\n \"cardnumber\": \"4242424242424242\",\n \"currency_code\": \"USD\",\n \"cvv\": \"123\",\n \"description\": \"Order placed over the phone\",\n \"expiry_month\": \"12\",\n \"expiry_year\": \"28\",\n \"method\": \"charge\",\n \"parameters\": {\n \"payment_id\": \"pay_8320b449b06630271e378214dab80ce5\",\n \"profile_id\": \"pro_GUMsmmzTU7oadT00pJeo\"\n },\n \"postal_code\": \"94122\",\n \"transaction_id\": \"IPe16430-39ba-4820-bedc-7aad0762a487\"\n}"
response = http.request(request)
puts response.read_body{
"charge_id": "pay_8320b449b06630271e378214dab80ce5",
"error_code": null,
"error_message": null,
"parameters": {
"amount_capturable": "0",
"amount_received": "100",
"connector": "stripe",
"connector_transaction_id": "pi_3URyI8D5R7gDAGff17RhZpfW",
"merchant_order_reference_id": "IPe16430-39ba-4820-bedc-7aad0762a487",
"payment_id": "pay_8320b449b06630271e378214dab80ce5",
"status": "succeeded"
}
}Authorizations
HTTP Basic authentication with a merchant API key as the password. The username is ignored. Used by endpoints that a third party posts to, such as telephone order providers.
Path Parameters
The unique identifier for the merchant account the card is charged under
The telephone order provider posting the request. Currently only twilio.
Body
application/json
The provider's charge request. Shown here in Twilio's Generic Pay Connector shape.
The operation Twilio is asking us to perform.
Available options:
charge, tokenize Twilio's id for this attempt. Stable across its retries, and used to derive the payment_id so a retry replays the original charge.
Example:
"IPe16430-39ba-4820-bedc-7aad0762a487"
Card number collected over DTMF. Required for a charge.
Example:
"4242424242424242"
Card security code collected over DTMF. Required for a charge.
Example:
"123"
Two digit card expiry month. Required for a charge.
Example:
"12"
Two or four digit card expiry year. Required for a charge.
Example:
"28"
Billing postal code, collected for AVS.
Example:
"94122"
Bank account number for ACH debits. Not supported.
Bank routing number for ACH debits. Not supported.
Amount in major units, as a decimal string. Absent for tokenize.
Example:
"1.00"
The three-letter ISO 4217 currency code (e.g., "USD", "EUR") for the payment amount. This field is mandatory for creating a payment.
Available options:
AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTN, BWP, BYN, BZD, CAD, CDF, CHF, CLF, CLP, CNY, COP, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, INR, IQD, IRR, ISK, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRU, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLE, SLL, SOS, SRD, SSP, STD, STN, SVC, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VES, VND, VUV, WST, XAF, XCD, XOF, XPF, YER, ZAR, ZMW, ZWL Free-form description configured on the <Pay> verb.
Example:
"Order placed over the phone"
Values from the IVR's <Parameter> tags, stored unmasked in the payment's metadata. profile_id, payment_id and customer_id are also read.
Response
The outcome of the charge, in the provider's response shape.
Body Twilio expects back. It reads error_code to decide the outcome, so a decline is a 200 with that set.
Returned either way, and the only channel carrying a payment_id when charge_id is null. Flat and all-string; the request's own parameters are never echoed back.
The Hyperswitch payment_id, on a successful charge.
Example:
"pay_8320b449b06630271e378214dab80ce5"
Set when the payment did not succeed: the connector's decline code, or one of INVALID_REQUEST, PROFILE_NOT_FOUND, PAYMENT_NOT_COMPLETED, PAYMENT_PENDING, DUPLICATE_TRANSACTION, PROCESSING_ERROR, TOKENIZE_UNSUPPORTED, BANK_ACCOUNT_UNSUPPORTED. On PAYMENT_PENDING the funds may be held, so do not re-prompt for a card.
Example:
"PAYMENT_NOT_COMPLETED"
Human readable counterpart to error_code.
Example:
"Your card was declined."
Was this page helpful?