Create a checkout session

curl --request POST \
  --url https://api.ringup.dev/v1/create_checkout \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "merchant_number": "+14155550100",
  "caller_phone": "+14155550142",
  "order_id": "8QK4M2XJ",
  "platform_call_id": "call_7c2a91e4",
  "return_to": "https://example.com/calls/7c2a91e4",
  "success_message": "You're all set. Your order will be ready in about ten minutes.",
  "failure_message": "That card did not go through. I can text you a link instead.",
  "metadata": {
    "ticket": "4821"
  }
}
EOF

import requests

url = "https://api.ringup.dev/v1/create_checkout"

payload = {
    "merchant_number": "+14155550100",
    "caller_phone": "+14155550142",
    "order_id": "8QK4M2XJ",
    "platform_call_id": "call_7c2a91e4",
    "return_to": "https://example.com/calls/7c2a91e4",
    "success_message": "You're all set. Your order will be ready in about ten minutes.",
    "failure_message": "That card did not go through. I can text you a link instead.",
    "metadata": { "ticket": "4821" }
}
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({
    merchant_number: '+14155550100',
    caller_phone: '+14155550142',
    order_id: '8QK4M2XJ',
    platform_call_id: 'call_7c2a91e4',
    return_to: 'https://example.com/calls/7c2a91e4',
    success_message: 'You\'re all set. Your order will be ready in about ten minutes.',
    failure_message: 'That card did not go through. I can text you a link instead.',
    metadata: {ticket: '4821'}
  })
};

fetch('https://api.ringup.dev/v1/create_checkout', 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://api.ringup.dev/v1/create_checkout",
  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([
    'merchant_number' => '+14155550100',
    'caller_phone' => '+14155550142',
    'order_id' => '8QK4M2XJ',
    'platform_call_id' => 'call_7c2a91e4',
    'return_to' => 'https://example.com/calls/7c2a91e4',
    'success_message' => 'You\'re all set. Your order will be ready in about ten minutes.',
    'failure_message' => 'That card did not go through. I can text you a link instead.',
    'metadata' => [
        'ticket' => '4821'
    ]
  ]),
  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://api.ringup.dev/v1/create_checkout"

	payload := strings.NewReader("{\n  \"merchant_number\": \"+14155550100\",\n  \"caller_phone\": \"+14155550142\",\n  \"order_id\": \"8QK4M2XJ\",\n  \"platform_call_id\": \"call_7c2a91e4\",\n  \"return_to\": \"https://example.com/calls/7c2a91e4\",\n  \"success_message\": \"You're all set. Your order will be ready in about ten minutes.\",\n  \"failure_message\": \"That card did not go through. I can text you a link instead.\",\n  \"metadata\": {\n    \"ticket\": \"4821\"\n  }\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://api.ringup.dev/v1/create_checkout")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"merchant_number\": \"+14155550100\",\n  \"caller_phone\": \"+14155550142\",\n  \"order_id\": \"8QK4M2XJ\",\n  \"platform_call_id\": \"call_7c2a91e4\",\n  \"return_to\": \"https://example.com/calls/7c2a91e4\",\n  \"success_message\": \"You're all set. Your order will be ready in about ten minutes.\",\n  \"failure_message\": \"That card did not go through. I can text you a link instead.\",\n  \"metadata\": {\n    \"ticket\": \"4821\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.ringup.dev/v1/create_checkout")

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  \"merchant_number\": \"+14155550100\",\n  \"caller_phone\": \"+14155550142\",\n  \"order_id\": \"8QK4M2XJ\",\n  \"platform_call_id\": \"call_7c2a91e4\",\n  \"return_to\": \"https://example.com/calls/7c2a91e4\",\n  \"success_message\": \"You're all set. Your order will be ready in about ten minutes.\",\n  \"failure_message\": \"That card did not go through. I can text you a link instead.\",\n  \"metadata\": {\n    \"ticket\": \"4821\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "checkout_session_id": "cs_test_453b5401286d0f80",
  "merchant_id": "mch_4f2c9a1b7e3d",
  "agent_message": "Payment is ready. Transferring the caller now.",
  "payment_required": "required",
  "amount_cents": 1650,
  "currency": "USD",
  "amount_source": "order",
  "transfer_to": "sip:eyJjIjoiKzE0MTU1NTUwMTQyIiwiYSI6MTY1MCwibSI6Im1jaF80ZjJjOWExYjdlM2QifQ.Xr7QpN2vK9sLd4TfA1mYc8BhE3wZ@transfer.ringup.dev",
  "transfer_to_number": "+16283364058",
  "expires_at": "2026-07-21T18:34:12.000Z",
  "cards": [
    {
      "instrument_id": "ins_9d21c7",
      "brand": "VISA",
      "last_four": "5858",
      "expiry": "07/2028"
    }
  ],
  "default_card_id": "ins_9d21c7",
  "metadata": {
    "ticket": "4821"
  }
}

POST

create_checkout

Create a checkout session

curl --request POST \
  --url https://api.ringup.dev/v1/create_checkout \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "merchant_number": "+14155550100",
  "caller_phone": "+14155550142",
  "order_id": "8QK4M2XJ",
  "platform_call_id": "call_7c2a91e4",
  "return_to": "https://example.com/calls/7c2a91e4",
  "success_message": "You're all set. Your order will be ready in about ten minutes.",
  "failure_message": "That card did not go through. I can text you a link instead.",
  "metadata": {
    "ticket": "4821"
  }
}
EOF

import requests

url = "https://api.ringup.dev/v1/create_checkout"

payload = {
    "merchant_number": "+14155550100",
    "caller_phone": "+14155550142",
    "order_id": "8QK4M2XJ",
    "platform_call_id": "call_7c2a91e4",
    "return_to": "https://example.com/calls/7c2a91e4",
    "success_message": "You're all set. Your order will be ready in about ten minutes.",
    "failure_message": "That card did not go through. I can text you a link instead.",
    "metadata": { "ticket": "4821" }
}
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({
    merchant_number: '+14155550100',
    caller_phone: '+14155550142',
    order_id: '8QK4M2XJ',
    platform_call_id: 'call_7c2a91e4',
    return_to: 'https://example.com/calls/7c2a91e4',
    success_message: 'You\'re all set. Your order will be ready in about ten minutes.',
    failure_message: 'That card did not go through. I can text you a link instead.',
    metadata: {ticket: '4821'}
  })
};

fetch('https://api.ringup.dev/v1/create_checkout', 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://api.ringup.dev/v1/create_checkout",
  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([
    'merchant_number' => '+14155550100',
    'caller_phone' => '+14155550142',
    'order_id' => '8QK4M2XJ',
    'platform_call_id' => 'call_7c2a91e4',
    'return_to' => 'https://example.com/calls/7c2a91e4',
    'success_message' => 'You\'re all set. Your order will be ready in about ten minutes.',
    'failure_message' => 'That card did not go through. I can text you a link instead.',
    'metadata' => [
        'ticket' => '4821'
    ]
  ]),
  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://api.ringup.dev/v1/create_checkout"

	payload := strings.NewReader("{\n  \"merchant_number\": \"+14155550100\",\n  \"caller_phone\": \"+14155550142\",\n  \"order_id\": \"8QK4M2XJ\",\n  \"platform_call_id\": \"call_7c2a91e4\",\n  \"return_to\": \"https://example.com/calls/7c2a91e4\",\n  \"success_message\": \"You're all set. Your order will be ready in about ten minutes.\",\n  \"failure_message\": \"That card did not go through. I can text you a link instead.\",\n  \"metadata\": {\n    \"ticket\": \"4821\"\n  }\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://api.ringup.dev/v1/create_checkout")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"merchant_number\": \"+14155550100\",\n  \"caller_phone\": \"+14155550142\",\n  \"order_id\": \"8QK4M2XJ\",\n  \"platform_call_id\": \"call_7c2a91e4\",\n  \"return_to\": \"https://example.com/calls/7c2a91e4\",\n  \"success_message\": \"You're all set. Your order will be ready in about ten minutes.\",\n  \"failure_message\": \"That card did not go through. I can text you a link instead.\",\n  \"metadata\": {\n    \"ticket\": \"4821\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.ringup.dev/v1/create_checkout")

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  \"merchant_number\": \"+14155550100\",\n  \"caller_phone\": \"+14155550142\",\n  \"order_id\": \"8QK4M2XJ\",\n  \"platform_call_id\": \"call_7c2a91e4\",\n  \"return_to\": \"https://example.com/calls/7c2a91e4\",\n  \"success_message\": \"You're all set. Your order will be ready in about ten minutes.\",\n  \"failure_message\": \"That card did not go through. I can text you a link instead.\",\n  \"metadata\": {\n    \"ticket\": \"4821\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "checkout_session_id": "cs_test_453b5401286d0f80",
  "merchant_id": "mch_4f2c9a1b7e3d",
  "agent_message": "Payment is ready. Transferring the caller now.",
  "payment_required": "required",
  "amount_cents": 1650,
  "currency": "USD",
  "amount_source": "order",
  "transfer_to": "sip:eyJjIjoiKzE0MTU1NTUwMTQyIiwiYSI6MTY1MCwibSI6Im1jaF80ZjJjOWExYjdlM2QifQ.Xr7QpN2vK9sLd4TfA1mYc8BhE3wZ@transfer.ringup.dev",
  "transfer_to_number": "+16283364058",
  "expires_at": "2026-07-21T18:34:12.000Z",
  "cards": [
    {
      "instrument_id": "ins_9d21c7",
      "brand": "VISA",
      "last_four": "5858",
      "expiry": "07/2028"
    }
  ],
  "default_card_id": "ins_9d21c7",
  "metadata": {
    "ticket": "4821"
  }
}

Authorizations

Authorization

string

header

required

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

Body

application/json

caller_phone

string

required

amount_cents

number

Required only when there is no order_id. Never trusted over an order.

currency

string

failure_message

string

Spoken after a failed one.

merchant_id

string

The merchant, when the caller knows it (a developer integrating over REST).

merchant_number

string

The merchant's own dialed number, when the caller knows the CALL but not the merchant (the transfer tool). Resolved to a merchant within the authed vendor; an unregistered number is an inaudible none, not an error (R13c-ii).

metadata

object

Your own key/value pairs. Opaque to Ringup: stored, echoed, never interpreted.

Show child attributes

order_id

string

The merchant's POS order. THE amount authority when present.

platform_call_id

string

The voice platform's id for this call. Functional, not metadata: we call the platform with it to verify caller attestation. Recommended.

return_to

string

Where to send the caller back after payment.

success_message

string

Spoken after a successful payment.

Response

Success.

agent_message

string

The one line a voice agent should say for this outcome, so the transfer tool never invents copy: "no payment is needed", "transferring you now", or "payment is unavailable" all come from here (R13c-ii). Errors carry the same field under error.agent_message.

amount_cents

number

What we RESOLVED. Under the order model the total is derived, so we must return it.

amount_source

enum<string>

Where the total came from, so a derived amount is visibly derived.

Available options:

order,

request

cards

object[]

Cards chargeable AT THIS MERCHANT, newest first. Handle-aware, not merely silo-aware: a Clover card enrolled at merchant A has no charge handle at merchant B, and offering it would fail at charge after the caller had already agreed to it. Empty means text a link.

Show child attributes

checkout_session_id

string

currency

string

default_card_id

string | null

expires_at

string

merchant_id

string

The merchant this resolved to, echoed back. Useful when the caller passed a merchant_number and wants to know which merchant it matched; empty string when no merchant resolved (an inaudible none, R13c-ii).

metadata

object | null

Show child attributes

payment_required

enum<string>

Available options:

required,

optional,

none

transfer_to

string | null

Null unless payment is required. Nothing to transfer to means do not transfer.

transfer_to_number

string | null

The same hand-off as a plain phone number, for platforms that can only transfer calls to a number. The call arrives without the token and the payment line resolves the session by the caller's number. Prefer transfer_to when the platform can dial a SIP URI.

API reference

Tools

Events

Errors

Create a checkout session

Authorizations

Body

Response