Languages: every operation supports cURL, Node.js (TypeScript), Python, Go, Ruby, and PHP. The first 15 operations on this page show all six languages; the remaining 37 show cURL and TypeScript — the two most-used.

Commerce API

Commerce endpoints exposed by the Devotel CPaaS API Base path: /api/v1/commerce Endpoint count: 52

title: “Errors worth branching on” description: “Per-endpoint failure templates matching the envelope — what actually fires, what to retry, what to surface to the operator.”

Errors worth branching on

These five failures cover the charge create (POST /api/v1/commerce/charges), which one-tap checkout fires per order. Each block below is a full { error, meta } envelope as the API returns it, and the matrix at the bottom answers retry vs surface for the same five classes. For the platform-wide decision table these branches plug into, see the error handling guide.

401 — Unauthorized

  {
    "error": {
      "code": "UNAUTHORIZED",
      "message": "The API key is invalid, expired, or lacks the required scope.",
      "status": 401
    },
    "meta": {
      "request_id": "req_commercea1",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 401 on this page is the bearer key failing before the route ran — it never means the resource is wrong. Rotate the key or re-mint the scoped token; retrying the same request changes nothing.

403 — Forbidden

  {
    "error": {
      "code": "FORBIDDEN",
      "message": "The key is valid but does not have the scope this operation requires.",
      "status": 403
    },
    "meta": {
      "request_id": "req_commercea1f",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 403 means the key authenticated but the operation is gated by scope — check the key’s scopes on the developer page; a 403 is never a data-not-found shape.

422 — Schema

  {
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "The request failed input validation.",
      "status": 422,
      "details": { "field": "mandate_id", "value": "mnd", "expected": "the full mandate id, formatted as mnd_<24-chars>" }
    },
    "meta": {
      "request_id": "req_commerceb2",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 422 means the payload did not match the request schema — branch on error.details.field and resend with the full mandate id instead of blind-retrying the same body.

429 — Rate

  {
    "error": {
      "code": "RATE_LIMITED",
      "message": "Too many requests in the current window.",
      "status": 429,
      "details": { "retry_after": 12 }
    },
    "meta": {
      "request_id": "req_commercec3",
      "timestamp": "2026-09-03T12:00:00Z",
      "docs_url": "https://docs.orbit.devotel.io/errors/RATE_LIMITED"
    }
  }

The Retry-After header and error.details.retry_after are both set on every 429 — resend the SAME request after the lower of the two.

409 — Conflict

  {
    "error": {
      "code": "COMMERCE_MANDATE_ALREADY_SPENT",
      "message": "This mandate's allowance was already committed against an earlier charge.",
      "status": 409,
      "details": { "mandate_id": "mnd_0192" }
    },
    "meta": {
      "request_id": "req_commerced4",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

Treat as idempotent-replay protection — return the original receipt instead of re-charging.

60-second retry matrix

Class	Meaning	Branch response
401 `UNAUTHORIZED`	the bearer key itself fails	Surface. Rotate the key or re-mint the scoped token; do not retry the same request.
403 `FORBIDDEN`	the key lacks this operation’s scope	Surface. Fix the key’s scope set; a retry with the same key never heals it.
422 `VALIDATION_ERROR`	the payload does not match the schema	Fix, then resend intentionally. Branch on `error.details.field`; a blind retry repeats the same 422.
429 `RATE_LIMITED`	the window quota is exhausted	Retry after `error.details.retry_after` (or the `Retry-After` header) with the same request body.
`COMMERCE_MANDATE_ALREADY_SPENT` (409 conflict)	Treat as idempotent-replay protection	Branch on `error.code`. Return the original receipt instead of re-charging.

Read the stored public ACP storefront config

GET /api/v1/commerce/agentic/storefront

Read this tenant’s STORED, agent-facing ACP storefront config (merchant name, currency, categories, catalog, and the publish switch) that the public edge serves at /public/commerce/acp/:storefrontId/..., plus the public storefront URL a merchant hands to a shopping agent. config is null when no storefront has been configured.

string (enum: true|false)

Sandbox opt-in for Clerk-session-authenticated requests. Set to true to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response meta.test_mode: true. Ignored for live API keys (dv_live_sk_*) — server-to-server clients must use a test-prefixed key (dv_test_sk_*) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/commerce/agentic/storefront" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/agentic/storefront', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/commerce/agentic/storefront", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/commerce/agentic/storefront", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/commerce/agentic/storefront')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/commerce/agentic/storefront');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": {
    "storefrontId": "string",
    "publicUrl": "string",
    "published": false
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Issue an agent payment mandate

POST /api/v1/commerce/agent-mandate

Issue a fresh scoped, revocable, spend-capped payment mandate for an agent.

string

Stripe-style idempotency token. Pass a stable, client-generated value (1-255 chars) to dedupe retries on transient timeouts. The same key+credential+path replays the original response for 24h on 2xx (5min on 4xx, 30s on 5xx). Returns 409 if a concurrent request with the same key is already in flight; replayed responses include the Idempotency-Replay: true response header.

string (enum: true|false)

string

required

—

string

required

—

string

required

—

number

required

—

number

required

—

string

required

—

array | null

—

array | null

—

integer | null

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/agent-mandate" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "string",
  "agentId": "string",
  "principalId": "string",
  "maxPerTransaction": 0,
  "totalCap": 0,
  "currency": "string"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/agent-mandate', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "id": "string",
  "agentId": "string",
  "principalId": "string",
  "maxPerTransaction": 0,
  "totalCap": 0,
  "currency": "string"
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/commerce/agent-mandate", headers=headers, json={
  "id": "string",
  "agentId": "string",
  "principalId": "string",
  "maxPerTransaction": 0,
  "totalCap": 0,
  "currency": "string"
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/commerce/agent-mandate", bytes.NewBuffer([]byte(`{
  "id": "string",
  "agentId": "string",
  "principalId": "string",
  "maxPerTransaction": 0,
  "totalCap": 0,
  "currency": "string"
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/commerce/agent-mandate')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "id": "string",
  "agentId": "string",
  "principalId": "string",
  "maxPerTransaction": 0,
  "totalCap": 0,
  "currency": "string"
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/commerce/agent-mandate');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "id": "string",
  "agentId": "string",
  "principalId": "string",
  "maxPerTransaction": 0,
  "totalCap": 0,
  "currency": "string"
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
    "agentId": "string",
    "principalId": "string",
    "maxPerTransaction": 0,
    "totalCap": 0,
    "currency": "string",
    "allowedMerchants": [
      "string"
    ],
    "allowedCategories": [
      "string"
    ],
    "spent": 0,
    "authorizationCount": 0,
    "status": "active",
    "consentDigest": "string",
    "expiresAt": null,
    "createdAt": 0,
    "updatedAt": 0,
    "revokedAt": null
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Dry-run authorize a charge against a mandate

POST /api/v1/commerce/agent-mandate/authorize

Dry-run a charge against a mandate and return the decision WITHOUT advancing spend.

string

string (enum: true|false)

object

required

Serializable AP2-style payment mandate snapshot. Carries a SHA-256 consent digest re-verified before every spend.

object

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/agent-mandate/authorize" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "mandate": {},
  "charge": {}
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/agent-mandate/authorize', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "mandate": {},
  "charge": {}
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/commerce/agent-mandate/authorize", headers=headers, json={
  "mandate": {},
  "charge": {}
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/commerce/agent-mandate/authorize", bytes.NewBuffer([]byte(`{
  "mandate": {},
  "charge": {}
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/commerce/agent-mandate/authorize')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "mandate": {},
  "charge": {}
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/commerce/agent-mandate/authorize');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "mandate": {},
  "charge": {}
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "authorization": {
      "authorized": false,
      "reason": "string",
      "authorizationId": "string",
      "remainingCap": 0,
      "settlement": null
    }
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Authorize and commit a charge

POST /api/v1/commerce/agent-mandate/charge

Authorize AND commit a charge, returning the advanced mandate plus the authorization. A charge outside the mandate is rejected with VALIDATION_ERROR.

string

string (enum: true|false)

object

required

Serializable AP2-style payment mandate snapshot. Carries a SHA-256 consent digest re-verified before every spend.

object

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/agent-mandate/charge" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "mandate": {},
  "charge": {}
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/agent-mandate/charge', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "mandate": {},
  "charge": {}
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/commerce/agent-mandate/charge", headers=headers, json={
  "mandate": {},
  "charge": {}
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/commerce/agent-mandate/charge", bytes.NewBuffer([]byte(`{
  "mandate": {},
  "charge": {}
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/commerce/agent-mandate/charge')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "mandate": {},
  "charge": {}
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/commerce/agent-mandate/charge');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "mandate": {},
  "charge": {}
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "mandate": {
      "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
      "agentId": "string",
      "principalId": "string",
      "maxPerTransaction": 0,
      "totalCap": 0,
      "currency": "string",
      "allowedMerchants": [
        "string"
      ],
      "allowedCategories": [
        "string"
      ],
      "spent": 0,
      "authorizationCount": 0,
      "status": "active",
      "consentDigest": "string",
      "expiresAt": null,
      "createdAt": 0,
      "updatedAt": 0,
      "revokedAt": null
    },
    "authorization": {
      "authorized": false,
      "reason": "string",
      "authorizationId": "string",
      "remainingCap": 0,
      "settlement": null
    },
    "ap2Credential": null
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Mint a card-network agent payment token or trusted-agent credential

POST /api/v1/commerce/agent-mandate/network-token

Present an authorized mandate charge to a card network’s agentic-payment program (Mastercard Agent Pay pilot, Visa Trusted Agent Protocol) and mint a network-issued, scoped agent payment token — or, for Visa TAP, a cryptographic trusted-agent credential the agent attaches to its merchant request — IN PLACE OF a hosted PaymentRequest. Returns 503 NETWORK_TOKEN_NOT_CONFIGURED when the requested provider’s program is not provisioned for this deployment — fall back to /agent-mandate/charge + the hosted-link rail.

string

string (enum: true|false)

object

required

Serializable AP2-style payment mandate snapshot. Carries a SHA-256 consent digest re-verified before every spend.

object

required

—

string (enum: mastercard_agent_pay|visa_trusted_agent_protocol)

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/agent-mandate/network-token" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "mandate": {},
  "charge": {}
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/agent-mandate/network-token', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "mandate": {},
  "charge": {}
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/commerce/agent-mandate/network-token", headers=headers, json={
  "mandate": {},
  "charge": {}
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/commerce/agent-mandate/network-token", bytes.NewBuffer([]byte(`{
  "mandate": {},
  "charge": {}
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/commerce/agent-mandate/network-token')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "mandate": {},
  "charge": {}
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/commerce/agent-mandate/network-token');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "mandate": {},
  "charge": {}
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "mandate": {
      "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
      "agentId": "string",
      "principalId": "string",
      "maxPerTransaction": 0,
      "totalCap": 0,
      "currency": "string",
      "allowedMerchants": [
        "string"
      ],
      "allowedCategories": [
        "string"
      ],
      "spent": 0,
      "authorizationCount": 0,
      "status": "active",
      "consentDigest": "string",
      "expiresAt": null,
      "createdAt": 0,
      "updatedAt": 0,
      "revokedAt": null
    },
    "authorization": {
      "authorized": false,
      "reason": "string",
      "authorizationId": "string",
      "remainingCap": 0,
      "settlement": null
    },
    "networkToken": null
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Revoke a mandate

POST /api/v1/commerce/agent-mandate/revoke

Withdraw consent, moving the mandate to the terminal revoked status. Re-revoking is a VALIDATION_ERROR.

string

string (enum: true|false)

object

required

Serializable AP2-style payment mandate snapshot. Carries a SHA-256 consent digest re-verified before every spend.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/agent-mandate/revoke" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "mandate": {}
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/agent-mandate/revoke', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "mandate": {}
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/commerce/agent-mandate/revoke", headers=headers, json={
  "mandate": {}
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/commerce/agent-mandate/revoke", bytes.NewBuffer([]byte(`{
  "mandate": {}
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/commerce/agent-mandate/revoke')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "mandate": {}
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/commerce/agent-mandate/revoke');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "mandate": {}
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
    "agentId": "string",
    "principalId": "string",
    "maxPerTransaction": 0,
    "totalCap": 0,
    "currency": "string",
    "allowedMerchants": [
      "string"
    ],
    "allowedCategories": [
      "string"
    ],
    "spent": 0,
    "authorizationCount": 0,
    "status": "active",
    "consentDigest": "string",
    "expiresAt": null,
    "createdAt": 0,
    "updatedAt": 0,
    "revokedAt": null
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Verify mandate integrity

POST /api/v1/commerce/agent-mandate/verify

Recompute the consent digest and report whether the mandate’s scope is intact (tamper-evidence for auditors).

string

string (enum: true|false)

object

required

Serializable AP2-style payment mandate snapshot. Carries a SHA-256 consent digest re-verified before every spend.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/agent-mandate/verify" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "mandate": {}
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/agent-mandate/verify', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "mandate": {}
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/commerce/agent-mandate/verify", headers=headers, json={
  "mandate": {}
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/commerce/agent-mandate/verify", bytes.NewBuffer([]byte(`{
  "mandate": {}
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/commerce/agent-mandate/verify')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "mandate": {}
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/commerce/agent-mandate/verify');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "mandate": {}
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "intact": false,
    "mandateId": "string",
    "consentDigest": "string"
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Open an ACP checkout session

POST /api/v1/commerce/agentic/checkout

Open an ACP checkout session, pricing the agent’s requested items SERVER-SIDE against the merchant catalog. Unknown / out-of-stock / wrong-currency lines are surfaced as blocking messages and keep the session not_ready_for_payment.

string

string (enum: true|false)

string

required

—

string

required

—

object[]

required

—

object[]

required

—

string | null

—

string | null

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/agentic/checkout" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "string",
  "merchantId": "string",
  "items": [],
  "catalog": []
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/agentic/checkout', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "id": "string",
  "merchantId": "string",
  "items": [],
  "catalog": []
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/commerce/agentic/checkout", headers=headers, json={
  "id": "string",
  "merchantId": "string",
  "items": [],
  "catalog": []
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/commerce/agentic/checkout", bytes.NewBuffer([]byte(`{
  "id": "string",
  "merchantId": "string",
  "items": [],
  "catalog": []
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/commerce/agentic/checkout')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "id": "string",
  "merchantId": "string",
  "items": [],
  "catalog": []
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/commerce/agentic/checkout');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "id": "string",
  "merchantId": "string",
  "items": [],
  "catalog": []
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
    "merchantId": "string",
    "status": "not_ready_for_payment",
    "currency": "string",
    "category": null,
    "lineItems": [
      {
        "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
        "productId": "string",
        "title": null,
        "quantity": 0,
        "unitPrice": 0,
        "currency": "string",
        "lineTotal": 0
      }
    ],
    "itemCount": 0,
    "subtotal": 0,
    "total": 0,
    "messages": [
      {
        "type": "error",
        "code": "string",
        "productId": null,
        "message": "string"
      }
    ],
    "order": null,
    "createdAt": 0,
    "updatedAt": 0
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Complete an ACP checkout under a signed mandate

POST /api/v1/commerce/agentic/checkout/complete

Complete a ready_for_payment session under an AP2 payment mandate. The session is re-priced SERVER-SIDE against the supplied catalog first (the incoming total is never trusted), then that re-priced total is charged against the mandate (consent digest + spend caps re-verified); a charge outside the mandate is rejected with VALIDATION_ERROR so an agent can never spend past signed consent. Mandate-only by default — no money moves and nothing is sent (invariant #45). When X402_ENABLED=1, the re-priced, mandate-authorized total is ALSO settled on-chain in USDC via the P1 x402 facilitator (requires an X-PAYMENT header — a missing/invalid header returns a 402 x402 challenge); the mandate spend is committed / the session moved to completed ONLY after settlement succeeds, otherwise the completion is rejected with a clean 402 SETTLEMENT_FAILED and the mandate is left untouched.

string

string (enum: true|false)

object

required

Serializable ACP checkout-session snapshot. Totals are re-derived server-side from the catalog and never trusted from the wire. Amounts are in MAJOR currency units.

object[]

required

—

object

required

Serializable AP2-style payment mandate snapshot. Carries a SHA-256 consent digest re-verified before every spend.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/agentic/checkout/complete" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "session": {},
  "catalog": [],
  "mandate": {}
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/agentic/checkout/complete', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "session": {},
  "catalog": [],
  "mandate": {}
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/commerce/agentic/checkout/complete", headers=headers, json={
  "session": {},
  "catalog": [],
  "mandate": {}
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/commerce/agentic/checkout/complete", bytes.NewBuffer([]byte(`{
  "session": {},
  "catalog": [],
  "mandate": {}
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/commerce/agentic/checkout/complete')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "session": {},
  "catalog": [],
  "mandate": {}
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/commerce/agentic/checkout/complete');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "session": {},
  "catalog": [],
  "mandate": {}
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "session": {
      "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
      "merchantId": "string",
      "status": "not_ready_for_payment",
      "currency": "string",
      "category": null,
      "lineItems": [
        {
          "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
          "productId": "string",
          "title": null,
          "quantity": 0,
          "unitPrice": 0,
          "currency": "string",
          "lineTotal": 0
        }
      ],
      "itemCount": 0,
      "subtotal": 0,
      "total": 0,
      "messages": [
        {
          "type": "error",
          "code": "string",
          "productId": null,
          "message": "string"
        }
      ],
      "order": null,
      "createdAt": 0,
      "updatedAt": 0
    },
    "mandate": {
      "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
      "agentId": "string",
      "principalId": "string",
      "maxPerTransaction": 0,
      "totalCap": 0,
      "currency": "string",
      "allowedMerchants": [
        "string"
      ],
      "allowedCategories": [
        "string"
      ],
      "spent": 0,
      "authorizationCount": 0,
      "status": "active",
      "consentDigest": "string",
      "expiresAt": null,
      "createdAt": 0,
      "updatedAt": 0,
      "revokedAt": null
    },
    "authorization": {
      "authorized": false,
      "reason": "string",
      "authorizationId": "string",
      "remainingCap": 0,
      "settlement": null
    },
    "settlement": null,
    "ap2Credential": null
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Re-price an ACP checkout session

POST /api/v1/commerce/agentic/checkout/update

Re-price a checkout session for a new requested-item set (replace-items semantics) and re-derive its status. A completed / canceled session is immutable and rejected with VALIDATION_ERROR.

string

string (enum: true|false)

object

required

Serializable ACP checkout-session snapshot. Totals are re-derived server-side from the catalog and never trusted from the wire. Amounts are in MAJOR currency units.

object[]

required

—

object[]

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/agentic/checkout/update" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "session": {},
  "items": [],
  "catalog": []
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/agentic/checkout/update', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "session": {},
  "items": [],
  "catalog": []
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/commerce/agentic/checkout/update", headers=headers, json={
  "session": {},
  "items": [],
  "catalog": []
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/commerce/agentic/checkout/update", bytes.NewBuffer([]byte(`{
  "session": {},
  "items": [],
  "catalog": []
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/commerce/agentic/checkout/update')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "session": {},
  "items": [],
  "catalog": []
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/commerce/agentic/checkout/update');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "session": {},
  "items": [],
  "catalog": []
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
    "merchantId": "string",
    "status": "not_ready_for_payment",
    "currency": "string",
    "category": null,
    "lineItems": [
      {
        "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
        "productId": "string",
        "title": null,
        "quantity": 0,
        "unitPrice": 0,
        "currency": "string",
        "lineTotal": 0
      }
    ],
    "itemCount": 0,
    "subtotal": 0,
    "total": 0,
    "messages": [
      {
        "type": "error",
        "code": "string",
        "productId": null,
        "message": "string"
      }
    ],
    "order": null,
    "createdAt": 0,
    "updatedAt": 0
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Build the ACP product feed

POST /api/v1/commerce/agentic/feed

Normalize a merchant catalog into the ACP product feed a shopping agent browses to discover what’s for sale (prices in MAJOR currency units; availability defaults to in_stock).

string

string (enum: true|false)

object[]

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/agentic/feed" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "products": []
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/agentic/feed', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "products": []
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/commerce/agentic/feed", headers=headers, json={
  "products": []
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/commerce/agentic/feed", bytes.NewBuffer([]byte(`{
  "products": []
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/commerce/agentic/feed')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "products": []
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/commerce/agentic/feed');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "products": []
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "protocol": "string",
    "protocolVersion": "string",
    "count": 0,
    "items": [
      {
        "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
        "title": "string",
        "description": null,
        "price": 0,
        "currency": "string",
        "availability": "in_stock",
        "inventoryQuantity": null,
        "link": null,
        "category": null
      }
    ],
    "generatedAt": 0
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Build the ACP storefront manifest

POST /api/v1/commerce/agentic/manifest

Build the Agentic Commerce Protocol discovery manifest a merchant publishes for third-party AI shopping agents: protocol version, capabilities, accepted payment methods, and endpoint paths.

string

string (enum: true|false)

string

required

—

string

required

—

string

required

https origin the merchant’s ACP endpoints are served from.

string

required

—

array | null

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/agentic/manifest" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "merchantId": "string",
  "merchantName": "string",
  "baseUrl": "string",
  "currency": "string"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/agentic/manifest', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "merchantId": "string",
  "merchantName": "string",
  "baseUrl": "string",
  "currency": "string"
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/commerce/agentic/manifest", headers=headers, json={
  "merchantId": "string",
  "merchantName": "string",
  "baseUrl": "string",
  "currency": "string"
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/commerce/agentic/manifest", bytes.NewBuffer([]byte(`{
  "merchantId": "string",
  "merchantName": "string",
  "baseUrl": "string",
  "currency": "string"
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/commerce/agentic/manifest')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "merchantId": "string",
  "merchantName": "string",
  "baseUrl": "string",
  "currency": "string"
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/commerce/agentic/manifest');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "merchantId": "string",
  "merchantName": "string",
  "baseUrl": "string",
  "currency": "string"
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "protocol": "string",
    "protocolVersion": "string",
    "merchant": {
      "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
      "name": "string",
      "currency": "string",
      "categories": [
        "string"
      ]
    },
    "capabilities": {},
    "paymentMethods": [
      "string"
    ],
    "endpoints": {},
    "generatedAt": 0
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Resolve an in-thread Apple Messages for Business checkout

POST /api/v1/commerce/amb-checkout

Resolve native Apple Pay (where the tenant’s AMB agent is capability-enabled) or the hosted pay link, both anchored to one PaymentRequest snapshot.

string

string (enum: true|false)

object

required

—

object

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/amb-checkout" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "order": {},
  "config": {}
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/amb-checkout', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "order": {},
  "config": {}
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/commerce/amb-checkout", headers=headers, json={
  "order": {},
  "config": {}
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/commerce/amb-checkout", bytes.NewBuffer([]byte(`{
  "order": {},
  "config": {}
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/commerce/amb-checkout')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "order": {},
  "config": {}
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/commerce/amb-checkout');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "order": {},
  "config": {}
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "method": "string",
    "currency": "string",
    "subtotal": 0,
    "paymentRequest": {
      "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
      "amount": 0,
      "currency": "string",
      "description": null,
      "reference": null,
      "checkoutUrl": "string",
      "status": "pending",
      "expiresAt": null,
      "createdAt": 0,
      "updatedAt": 0
    }
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Create cart

POST /api/v1/commerce/cart

Create a fresh, empty omnichannel cart in the browsing state.

string

string (enum: true|false)

string

required

Caller-supplied opaque cart id, stable across channels.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/cart" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "cartId": "string"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/cart', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "cartId": "string"
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/commerce/cart", headers=headers, json={
  "cartId": "string"
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/commerce/cart", bytes.NewBuffer([]byte(`{
  "cartId": "string"
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/commerce/cart')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "cartId": "string"
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/commerce/cart');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "cartId": "string"
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "cartId": "string",
    "items": [
      {
        "productRetailerId": "string",
        "name": null,
        "quantity": 0,
        "unitPrice": 0,
        "currency": "string",
        "lineTotal": 0,
        "sourceChannels": [
          "whatsapp"
        ]
      }
    ],
    "lineCount": 0,
    "itemCount": 0,
    "subtotal": 0,
    "currency": "string",
    "mixedCurrency": false,
    "state": "browsing",
    "lastChannel": "whatsapp",
    "updatedAt": 0
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Check whether the cart is abandoned

POST /api/v1/commerce/cart/abandonment-check

True when the cart has gone quiet past idleThresholdMs while holding items in a recoverable, pre-payment state.

string

string (enum: true|false)

object

required

Serializable omnichannel cart snapshot. Derived fields (subtotal, itemCount, …) are re-computed server-side and never trusted.

integer

Idle threshold in ms. Defaults to 30 minutes; capped at 30 days.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/cart/abandonment-check" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "cart": {}
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/cart/abandonment-check', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "cart": {}
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/commerce/cart/abandonment-check", headers=headers, json={
  "cart": {}
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/commerce/cart/abandonment-check", bytes.NewBuffer([]byte(`{
  "cart": {}
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/commerce/cart/abandonment-check')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "cart": {}
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/commerce/cart/abandonment-check');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "cart": {}
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "abandoned": false,
    "idleMs": 0,
    "state": "browsing"
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Select checkout-channel preference order

POST /api/v1/commerce/cart/checkout-channel

Ordered checkout-channel preference for the cart, restricted to the tenant’s capable channels. An empty array signals fall back to a hosted payment link.

string

string (enum: true|false)

object

required

Serializable omnichannel cart snapshot. Derived fields (subtotal, itemCount, …) are re-computed server-side and never trusted.

string (enum: whatsapp|rcs|amb|instagram)[]

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/cart/checkout-channel" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "cart": {},
  "capableChannels": []
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/cart/checkout-channel', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "cart": {},
  "capableChannels": []
}),
})
console.log(await res.json())

{
  "data": {
    "channels": [
      "whatsapp"
    ],
    "preferenceOrder": [
      "whatsapp"
    ]
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Merge a channel contribution into the cart

POST /api/v1/commerce/cart/merge

Fold a per-channel order contribution into the cart and re-derive totals server-side.

string

string (enum: true|false)

object

required

Serializable omnichannel cart snapshot. Derived fields (subtotal, itemCount, …) are re-computed server-side and never trusted.

object

required

—

string (enum: whatsapp|rcs|amb|instagram)

required

Conversational-commerce channel a cart contribution came from.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/cart/merge" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "cart": {},
  "contribution": {},
  "channel": "whatsapp"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/cart/merge', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "cart": {},
  "contribution": {},
  "channel": "whatsapp"
}),
})
console.log(await res.json())

{
  "data": {
    "cartId": "string",
    "items": [
      {
        "productRetailerId": "string",
        "name": null,
        "quantity": 0,
        "unitPrice": 0,
        "currency": "string",
        "lineTotal": 0,
        "sourceChannels": [
          "whatsapp"
        ]
      }
    ],
    "lineCount": 0,
    "itemCount": 0,
    "subtotal": 0,
    "currency": "string",
    "mixedCurrency": false,
    "state": "browsing",
    "lastChannel": "whatsapp",
    "updatedAt": 0
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Reconcile a cross-channel payment against the cart

POST /api/v1/commerce/cart/reconcile-payment

Match a payment captured on ANY channel against the cart subtotal (totals re-derived server-side first).

string

string (enum: true|false)

object

required

Serializable omnichannel cart snapshot. Derived fields (subtotal, itemCount, …) are re-computed server-side and never trusted.

object

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/cart/reconcile-payment" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "cart": {},
  "payment": {}
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/cart/reconcile-payment', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "cart": {},
  "payment": {}
}),
})
console.log(await res.json())

{
  "data": {
    "matched": false,
    "delta": 0,
    "reason": "ok",
    "reference": "string",
    "channel": "whatsapp"
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Advance the checkout state machine

POST /api/v1/commerce/cart/transition

Apply one checkout event to the cart. An illegal transition is rejected with VALIDATION_ERROR.

string

string (enum: true|false)

object

required

Serializable omnichannel cart snapshot. Derived fields (subtotal, itemCount, …) are re-computed server-side and never trusted.

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/cart/transition" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "cart": {},
  "event": "ADD_ITEM"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/cart/transition', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "cart": {},
  "event": "ADD_ITEM"
}),
})
console.log(await res.json())

{
  "data": {
    "cartId": "string",
    "items": [
      {
        "productRetailerId": "string",
        "name": null,
        "quantity": 0,
        "unitPrice": 0,
        "currency": "string",
        "lineTotal": 0,
        "sourceChannels": [
          "whatsapp"
        ]
      }
    ],
    "lineCount": 0,
    "itemCount": 0,
    "subtotal": 0,
    "currency": "string",
    "mixedCurrency": false,
    "state": "browsing",
    "lastChannel": "whatsapp",
    "updatedAt": 0
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Initiate a DCB charge

POST /api/v1/commerce/dcb/charge

Validate a charge against the merchant’s coverage + per-transaction cap and return an initiated charge snapshot. The operator dip is submitted separately via the carrier-billing route.

string

string (enum: true|false)

object

required

Serializable DCB merchant config — settlement currency, per-transaction cap, and tenant-level operator coverage map.

object

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/dcb/charge" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "merchant": {},
  "charge": {}
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/dcb/charge', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "merchant": {},
  "charge": {}
}),
})
console.log(await res.json())

{
  "data": {
    "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
    "merchantId": "string",
    "country": "string",
    "operator": "string",
    "buyerMsisdnMasked": "string",
    "amount": 0,
    "currency": "string",
    "description": "string",
    "merchantReference": null,
    "status": "initiated",
    "capturedAmount": 0,
    "refundedAmount": 0,
    "createdAt": 0,
    "updatedAt": 0,
    "settledAt": null
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Capture a DCB charge

POST /api/v1/commerce/dcb/charge/capture

Mark an initiated charge captured once the operator confirms billing. capturedAmount defaults to the initiated amount and may not exceed it (partial capture honoured).

string

string (enum: true|false)

object

required

Serializable DCB charge snapshot. The buyer MSISDN is stored masked; the operator dip rides the carrier-billing route.

number

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/dcb/charge/capture" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "charge": {}
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/dcb/charge/capture', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "charge": {}
}),
})
console.log(await res.json())

{
  "data": {
    "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
    "merchantId": "string",
    "country": "string",
    "operator": "string",
    "buyerMsisdnMasked": "string",
    "amount": 0,
    "currency": "string",
    "description": "string",
    "merchantReference": null,
    "status": "initiated",
    "capturedAmount": 0,
    "refundedAmount": 0,
    "createdAt": 0,
    "updatedAt": 0,
    "settledAt": null
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Record a DCB chargeback

POST /api/v1/commerce/dcb/charge/chargeback

Record an operator-initiated chargeback, reversing the full net captured value and moving the charge to the terminal charged_back status.

string

string (enum: true|false)

object

required

Serializable DCB charge snapshot. The buyer MSISDN is stored masked; the operator dip rides the carrier-billing route.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/dcb/charge/chargeback" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "charge": {}
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/dcb/charge/chargeback', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "charge": {}
}),
})
console.log(await res.json())

{
  "data": {
    "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
    "merchantId": "string",
    "country": "string",
    "operator": "string",
    "buyerMsisdnMasked": "string",
    "amount": 0,
    "currency": "string",
    "description": "string",
    "merchantReference": null,
    "status": "initiated",
    "capturedAmount": 0,
    "refundedAmount": 0,
    "createdAt": 0,
    "updatedAt": 0,
    "settledAt": null
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Fail a DCB charge

POST /api/v1/commerce/dcb/charge/fail

Mark an initiated charge failed (operator declined). Terminal.

string

string (enum: true|false)

object

required

Serializable DCB charge snapshot. The buyer MSISDN is stored masked; the operator dip rides the carrier-billing route.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/dcb/charge/fail" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "charge": {}
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/dcb/charge/fail', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "charge": {}
}),
})
console.log(await res.json())

{
  "data": {
    "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
    "merchantId": "string",
    "country": "string",
    "operator": "string",
    "buyerMsisdnMasked": "string",
    "amount": 0,
    "currency": "string",
    "description": "string",
    "merchantReference": null,
    "status": "initiated",
    "capturedAmount": 0,
    "refundedAmount": 0,
    "createdAt": 0,
    "updatedAt": 0,
    "settledAt": null
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Refund a DCB charge

POST /api/v1/commerce/dcb/charge/refund

Refund part or all of a captured charge. A full-headroom refund moves the charge to refunded, a partial one to partially_refunded. Rejects a refund above the refundable headroom.

string

string (enum: true|false)

object

required

Serializable DCB charge snapshot. The buyer MSISDN is stored masked; the operator dip rides the carrier-billing route.

number

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/dcb/charge/refund" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "charge": {},
  "amount": 0
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/dcb/charge/refund', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "charge": {},
  "amount": 0
}),
})
console.log(await res.json())

{
  "data": {
    "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
    "merchantId": "string",
    "country": "string",
    "operator": "string",
    "buyerMsisdnMasked": "string",
    "amount": 0,
    "currency": "string",
    "description": "string",
    "merchantReference": null,
    "status": "initiated",
    "capturedAmount": 0,
    "refundedAmount": 0,
    "createdAt": 0,
    "updatedAt": 0,
    "settledAt": null
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Configure a DCB merchant

POST /api/v1/commerce/dcb/merchant

Onboard / reconfigure a Direct Carrier Billing merchant: settlement currency, digital-goods category, per-transaction cap, and the tenant-level operator coverage map.

string

string (enum: true|false)

string

required

—

string

required

—

string

required

—

string

required

—

number

required

—

object[]

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/dcb/merchant" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "merchantId": "string",
  "displayName": "string",
  "currency": "string",
  "category": "string",
  "maxChargeAmount": 0
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/dcb/merchant', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "merchantId": "string",
  "displayName": "string",
  "currency": "string",
  "category": "string",
  "maxChargeAmount": 0
}),
})
console.log(await res.json())

{
  "data": {
    "merchantId": "string",
    "displayName": "string",
    "currency": "string",
    "category": "string",
    "maxChargeAmount": 0,
    "coverage": [
      {
        "country": "string",
        "operator": "string",
        "status": "live"
      }
    ],
    "createdAt": 0,
    "updatedAt": 0
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Build the carrier-billing operator request

POST /api/v1/commerce/dcb/operator-request

Shape the /network-apis/carrier-billing:charge request body for an initiated charge + the raw buyer MSISDN (never stored on the snapshot). The caller submits the returned body to that route, which owns the cost cap + metering.

string

string (enum: true|false)

object

required

Serializable DCB charge snapshot. The buyer MSISDN is stored masked; the operator dip rides the carrier-billing route.

string

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/dcb/operator-request" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "charge": {},
  "phoneNumber": "+14155552671"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/dcb/operator-request', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "charge": {},
  "phoneNumber": "+14155552671"
}),
})
console.log(await res.json())

{
  "data": {
    "operatorRequest": {},
    "route": "string"
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Reconcile a DCB settlement

POST /api/v1/commerce/dcb/reconcile

Reconcile a batch of charges against operator settlement records. Each captured (or partially-refunded) charge is expected to settle for its net value; the report flags amount/currency mismatches, missing settlements, and unexpected lines, all derived server-side.

string

string (enum: true|false)

object[]

required

—

object[]

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/dcb/reconcile" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "charges": [],
  "records": []
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/dcb/reconcile', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "charges": [],
  "records": []
}),
})
console.log(await res.json())

{
  "data": {
    "report": {
      "matched": [
        "string"
      ],
      "mismatched": [
        "string"
      ],
      "missing": [
        "string"
      ],
      "unexpected": [
        "string"
      ],
      "grossCaptured": 0,
      "totalRefunded": 0,
      "chargebackCount": 0,
      "netExpected": 0,
      "netSettled": 0,
      "delta": 0,
      "reconciled": false
    },
    "settledCharges": [
      {
        "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
        "merchantId": "string",
        "country": "string",
        "operator": "string",
        "buyerMsisdnMasked": "string",
        "amount": 0,
        "currency": "string",
        "description": "string",
        "merchantReference": null,
        "status": "initiated",
        "capturedAmount": 0,
        "refundedAmount": 0,
        "createdAt": 0,
        "updatedAt": 0,
        "settledAt": null
      }
    ]
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Open an MPP pre-authorized session

POST /api/v1/commerce/mpp-session

Open a fresh MPP (Machine Payments Protocol) session: a spend cap + REQUIRED future expiry an agent pre-authorizes ONCE, then streams metered micropayments against.

string

string (enum: true|false)

string

required

—

string

required

—

string

required

—

number

required

—

number

required

—

string

required

—

integer

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/mpp-session" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "string",
  "agentId": "string",
  "principalId": "string",
  "spendCap": 0,
  "maxPerCall": 0,
  "currency": "string",
  "expiresAt": 0
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/mpp-session', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "id": "string",
  "agentId": "string",
  "principalId": "string",
  "spendCap": 0,
  "maxPerCall": 0,
  "currency": "string",
  "expiresAt": 0
}),
})
console.log(await res.json())

{
  "data": {
    "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
    "agentId": "string",
    "principalId": "string",
    "spendCap": 0,
    "maxPerCall": 0,
    "currency": "string",
    "spent": 0,
    "callCount": 0,
    "status": "active",
    "consentDigest": "string",
    "expiresAt": 0,
    "createdAt": 0,
    "updatedAt": 0,
    "revokedAt": null
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Meter and settle one call streamed against an MPP session

POST /api/v1/commerce/mpp-session/call

Meter one agent-tool-call / API request against an MPP session’s remaining cap and settle it via the x402 facilitator. Returns 503 MPP_SETTLEMENT_NOT_ENABLED unless X402_ENABLED=1. A declined call responds 200 with settlement: null. An authorized call with no/invalid X-PAYMENT header responds 402 with an x402 challenge; session spend is committed only once the facilitator reports settlement success.

string

string (enum: true|false)

object

required

Serializable MPP (Machine Payments Protocol) pre-authorized session snapshot — a spend cap + REQUIRED expiry an agent opens ONCE, then streams metered micropayments against. Carries a SHA-256 consent digest re-verified before every metered call.

object

required

—

string

required

—

string

required

—

string

required

—

string

required

The call’s price in ATOMIC units of asset, base-10 string.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/mpp-session/call" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "session": {},
  "call": {},
  "payTo": "string",
  "asset": "string",
  "network": "string",
  "atomicAmount": "string"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/mpp-session/call', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "session": {},
  "call": {},
  "payTo": "string",
  "asset": "string",
  "network": "string",
  "atomicAmount": "string"
}),
})
console.log(await res.json())

{
  "data": {
    "session": {
      "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
      "agentId": "string",
      "principalId": "string",
      "spendCap": 0,
      "maxPerCall": 0,
      "currency": "string",
      "spent": 0,
      "callCount": 0,
      "status": "active",
      "consentDigest": "string",
      "expiresAt": 0,
      "createdAt": 0,
      "updatedAt": 0,
      "revokedAt": null
    },
    "meter": {
      "authorized": false,
      "reason": "string",
      "sessionId": "string",
      "meterId": "string",
      "amount": 0,
      "resource": "string",
      "reference": "string",
      "remainingCap": 0
    },
    "settlement": null
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Dry-run meter a call against an MPP session

POST /api/v1/commerce/mpp-session/meter

Dry-run one metered agent-tool-call / API request against an MPP session and return the decision WITHOUT advancing spend.

string

string (enum: true|false)

object

required

object

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/mpp-session/meter" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "session": {},
  "call": {}
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/mpp-session/meter', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "session": {},
  "call": {}
}),
})
console.log(await res.json())

{
  "data": {
    "meter": {
      "authorized": false,
      "reason": "string",
      "sessionId": "string",
      "meterId": "string",
      "amount": 0,
      "resource": "string",
      "reference": "string",
      "remainingCap": 0
    }
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Revoke an MPP session

POST /api/v1/commerce/mpp-session/revoke

Withdraw a session’s pre-authorization, moving it to the terminal revoked status. Re-revoking is a VALIDATION_ERROR.

string

string (enum: true|false)

object

required

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/mpp-session/revoke" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "session": {}
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/mpp-session/revoke', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "session": {}
}),
})
console.log(await res.json())

{
  "data": {
    "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
    "agentId": "string",
    "principalId": "string",
    "spendCap": 0,
    "maxPerCall": 0,
    "currency": "string",
    "spent": 0,
    "callCount": 0,
    "status": "active",
    "consentDigest": "string",
    "expiresAt": 0,
    "createdAt": 0,
    "updatedAt": 0,
    "revokedAt": null
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Verify MPP session integrity

POST /api/v1/commerce/mpp-session/verify

Recompute the consent digest and report whether the session’s scope is intact (tamper-evidence for auditors).

string

string (enum: true|false)

object

required

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/mpp-session/verify" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "session": {}
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/mpp-session/verify', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "session": {}
}),
})
console.log(await res.json())

{
  "data": {
    "intact": false,
    "sessionId": "string",
    "consentDigest": "string"
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Mint a hosted pay-by-link

POST /api/v1/commerce/payment-request

Mint a fresh channel-agnostic hosted PSP-checkout link (PaymentRequest).

string

string (enum: true|false)

string

required

—

number

required

—

string

required

—

string

required

—

string | null

—

string | null

—

integer | null

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/payment-request" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "string",
  "amount": 0,
  "currency": "string",
  "hostedBaseUrl": "string"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/payment-request', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "id": "string",
  "amount": 0,
  "currency": "string",
  "hostedBaseUrl": "string"
}),
})
console.log(await res.json())

{
  "data": {
    "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
    "amount": 0,
    "currency": "string",
    "description": null,
    "reference": null,
    "checkoutUrl": "string",
    "status": "pending",
    "expiresAt": null,
    "createdAt": 0,
    "updatedAt": 0
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Reconcile a captured PSP payment

POST /api/v1/commerce/payment-request/reconcile

Match a captured PSP payment against the request. On an exact amount+currency match the request advances to paid.

string

string (enum: true|false)

object

required

Serializable channel-agnostic hosted pay-by-link snapshot. The caller round-trips it in each request body.

object

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/payment-request/reconcile" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "request": {},
  "capture": {}
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/payment-request/reconcile', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "request": {},
  "capture": {}
}),
})
console.log(await res.json())

{
  "data": {
    "reconciliation": {
      "matched": false,
      "reason": "string"
    },
    "request": {
      "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
      "amount": 0,
      "currency": "string",
      "description": null,
      "reference": null,
      "checkoutUrl": "string",
      "status": "pending",
      "expiresAt": null,
      "createdAt": 0,
      "updatedAt": 0
    },
    "channels": [
      "whatsapp"
    ]
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Render a pay-by-link for one channel

POST /api/v1/commerce/payment-request/render

Render the hosted link for a single channel; the caller hands the result to the existing per-channel send infra.

string

string (enum: true|false)

object

required

Serializable channel-agnostic hosted pay-by-link snapshot. The caller round-trips it in each request body.

string (enum: whatsapp|rcs|sms|email|telegram|viber|…)

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/payment-request/render" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "request": {},
  "channel": "whatsapp"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/payment-request/render', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "request": {},
  "channel": "whatsapp"
}),
})
console.log(await res.json())

{
  "data": {},
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Advance a pay-by-link lifecycle

POST /api/v1/commerce/payment-request/transition

Apply one lifecycle event to the payment request. An illegal transition is rejected with VALIDATION_ERROR.

string

string (enum: true|false)

object

required

Serializable channel-agnostic hosted pay-by-link snapshot. The caller round-trips it in each request body.

string (enum: MARK_VIEWED|MARK_PAID|EXPIRE|CANCEL)

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/payment-request/transition" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "request": {},
  "event": "MARK_VIEWED"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/payment-request/transition', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "request": {},
  "event": "MARK_VIEWED"
}),
})
console.log(await res.json())

{
  "data": {
    "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
    "amount": 0,
    "currency": "string",
    "description": null,
    "reference": null,
    "checkoutUrl": "string",
    "status": "pending",
    "expiresAt": null,
    "createdAt": 0,
    "updatedAt": 0
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Resolve an in-thread RCS checkout

POST /api/v1/commerce/rcs-checkout

Turn a captured RCS catalog order into the hosted pay link (RCS has no native wallet), anchored to one PaymentRequest snapshot the reconcile route closes out.

string

string (enum: true|false)

object

required

—

object

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/rcs-checkout" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "order": {},
  "config": {}
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/rcs-checkout', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "order": {},
  "config": {}
}),
})
console.log(await res.json())

{
  "data": {
    "method": "string",
    "currency": "string",
    "subtotal": 0,
    "paymentRequest": {
      "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
      "amount": 0,
      "currency": "string",
      "description": null,
      "reference": null,
      "checkoutUrl": "string",
      "status": "pending",
      "expiresAt": null,
      "createdAt": 0,
      "updatedAt": 0
    }
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Bind an in-call PCI capture to a commerce charge

POST /api/v1/commerce/secure-payment/charge

Bind a live-call masked-DTMF card capture (a completed voice secure-payment session) to the priced PaymentRequest as ONE commerce charge. The proof is derived SERVER-SIDE from the call’s persisted secure_payment_sessions metadata — caller capture fields (call_id + optional session_id/card_last4/card_brand/psp_token_ref) are consistency hints only and any mismatch with the stored masked summary fails closed; only a COMPLETE (non-cancelled, tokenized) capture session can bind. The PSP settles the opaque token out-of-band; the capture webhook closes the request out through /commerce/payment-request/reconcile with the same providerReference. The full PAN/CVV never reach this endpoint.

string

string (enum: true|false)

string

required

—

number

required

—

string

required

—

string | null

—

string | null

—

string | null

—

object

required

—

object[]

Charges already recorded by the caller, for the server-side double-charge guard (snapshot round-trip, mirrors omni-cart/PaymentRequest).

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/secure-payment/charge" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "charge_id": "string",
  "amount": 0,
  "currency": "string",
  "capture": {}
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/secure-payment/charge', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "charge_id": "string",
  "amount": 0,
  "currency": "string",
  "capture": {}
}),
})
console.log(await res.json())

{
  "data": {
    "charge": {},
    "reconciliation_capture": {}
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Start a recurring subscription

POST /api/v1/commerce/subscriptions

Start a recurring subscription off an existing cart/order, authorized against an already-issued payment mandate. Schedules the first renewal one interval out.

string

string (enum: true|false)

string

required

—

string

required

—

string

required

—

string

required

—

string (enum: whatsapp|rcs)

required

—

object[]

required

—

string

required

—

string (enum: weekly|biweekly|monthly|quarterly)

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/subscriptions" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "string",
  "cartId": "string",
  "principalId": "string",
  "mandateId": "string",
  "channel": "whatsapp",
  "items": [],
  "currency": "string",
  "interval": "weekly"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/subscriptions', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "id": "string",
  "cartId": "string",
  "principalId": "string",
  "mandateId": "string",
  "channel": "whatsapp",
  "items": [],
  "currency": "string",
  "interval": "weekly"
}),
})
console.log(await res.json())

{
  "data": {
    "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
    "cartId": "string",
    "principalId": "string",
    "mandateId": "string",
    "channel": "whatsapp",
    "items": [
      {
        "productRetailerId": "string",
        "name": null,
        "quantity": 0,
        "unitPrice": 0,
        "currency": "string"
      }
    ],
    "currency": "string",
    "amount": 0,
    "interval": "weekly",
    "status": "active",
    "cyclesCompleted": 0,
    "nextChargeAt": null,
    "lastRenewalAt": null,
    "lastRenewalReference": null,
    "createdAt": 0,
    "updatedAt": 0,
    "pausedAt": null,
    "canceledAt": null
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Cancel a subscription

POST /api/v1/commerce/subscriptions/cancel

Cancel a subscription — terminal; no further renewal is ever due. Re-canceling an already-canceled subscription is a VALIDATION_ERROR.

string

string (enum: true|false)

object

required

Serializable recurring subscription schedule snapshot. The renewal reuses the stored agent-payment-mandate authorization; the caller round-trips this snapshot in each request body.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/subscriptions/cancel" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "subscription": {}
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/subscriptions/cancel', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "subscription": {}
}),
})
console.log(await res.json())

{
  "data": {
    "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
    "cartId": "string",
    "principalId": "string",
    "mandateId": "string",
    "channel": "whatsapp",
    "items": [
      {
        "productRetailerId": "string",
        "name": null,
        "quantity": 0,
        "unitPrice": 0,
        "currency": "string"
      }
    ],
    "currency": "string",
    "amount": 0,
    "interval": "weekly",
    "status": "active",
    "cyclesCompleted": 0,
    "nextChargeAt": null,
    "lastRenewalAt": null,
    "lastRenewalReference": null,
    "createdAt": 0,
    "updatedAt": 0,
    "pausedAt": null,
    "canceledAt": null
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Annotate + sort a set of subscriptions

POST /api/v1/commerce/subscriptions/list

Annotate caller-supplied subscription snapshots with their renewal-due state and sort by next-charge date (soonest first).

string

string (enum: true|false)

object[]

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/subscriptions/list" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "subscriptions": []
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/subscriptions/list', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "subscriptions": []
}),
})
console.log(await res.json())

{
  "data": {
    "subscriptions": [
      {
        "subscription": {
          "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
          "cartId": "string",
          "principalId": "string",
          "mandateId": "string",
          "channel": "whatsapp",
          "items": [
            {
              "productRetailerId": "string",
              "name": null,
              "quantity": 0,
              "unitPrice": 0,
              "currency": "string"
            }
          ],
          "currency": "string",
          "amount": 0,
          "interval": "weekly",
          "status": "active",
          "cyclesCompleted": 0,
          "nextChargeAt": null,
          "lastRenewalAt": null,
          "lastRenewalReference": null,
          "createdAt": 0,
          "updatedAt": 0,
          "pausedAt": null,
          "canceledAt": null
        },
        "dueForRenewal": false
      }
    ]
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Pause a subscription

POST /api/v1/commerce/subscriptions/pause

Pause an active subscription; the renewal executor refuses to charge it until resumed.

string

string (enum: true|false)

object

required

Serializable recurring subscription schedule snapshot. The renewal reuses the stored agent-payment-mandate authorization; the caller round-trips this snapshot in each request body.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/subscriptions/pause" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "subscription": {}
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/subscriptions/pause', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "subscription": {}
}),
})
console.log(await res.json())

{
  "data": {
    "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
    "cartId": "string",
    "principalId": "string",
    "mandateId": "string",
    "channel": "whatsapp",
    "items": [
      {
        "productRetailerId": "string",
        "name": null,
        "quantity": 0,
        "unitPrice": 0,
        "currency": "string"
      }
    ],
    "currency": "string",
    "amount": 0,
    "interval": "weekly",
    "status": "active",
    "cyclesCompleted": 0,
    "nextChargeAt": null,
    "lastRenewalAt": null,
    "lastRenewalReference": null,
    "createdAt": 0,
    "updatedAt": 0,
    "pausedAt": null,
    "canceledAt": null
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Fire a due subscription renewal cycle

POST /api/v1/commerce/subscriptions/renew

Authorize+commit the cycle’s charge against the stored payment mandate (no new consent collected), mint the reorder’s RCS/WhatsApp checkout, and advance the schedule. Rejected with VALIDATION_ERROR when the subscription isn’t active/due, or when the mandate declines the charge.

string

string (enum: true|false)

object

required

Serializable recurring subscription schedule snapshot. The renewal reuses the stored agent-payment-mandate authorization; the caller round-trips this snapshot in each request body.

object

required

Serializable AP2-style payment mandate snapshot. Carries a SHA-256 consent digest re-verified before every spend.

object

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/subscriptions/renew" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "subscription": {},
  "mandate": {},
  "config": {}
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/subscriptions/renew', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "subscription": {},
  "mandate": {},
  "config": {}
}),
})
console.log(await res.json())

{
  "data": {
    "subscription": {
      "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
      "cartId": "string",
      "principalId": "string",
      "mandateId": "string",
      "channel": "whatsapp",
      "items": [
        {
          "productRetailerId": "string",
          "name": null,
          "quantity": 0,
          "unitPrice": 0,
          "currency": "string"
        }
      ],
      "currency": "string",
      "amount": 0,
      "interval": "weekly",
      "status": "active",
      "cyclesCompleted": 0,
      "nextChargeAt": null,
      "lastRenewalAt": null,
      "lastRenewalReference": null,
      "createdAt": 0,
      "updatedAt": 0,
      "pausedAt": null,
      "canceledAt": null
    },
    "mandate": {
      "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
      "agentId": "string",
      "principalId": "string",
      "maxPerTransaction": 0,
      "totalCap": 0,
      "currency": "string",
      "allowedMerchants": [
        "string"
      ],
      "allowedCategories": [
        "string"
      ],
      "spent": 0,
      "authorizationCount": 0,
      "status": "active",
      "consentDigest": "string",
      "expiresAt": null,
      "createdAt": 0,
      "updatedAt": 0,
      "revokedAt": null
    },
    "checkout": {},
    "webhookEvent": {
      "event": "string",
      "subscriptionId": "string",
      "cycleNumber": 0,
      "amount": 0,
      "currency": "string",
      "channel": "whatsapp",
      "chargeReference": "string",
      "nextChargeAt": null,
      "occurredAt": 0
    }
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Resume a paused subscription

POST /api/v1/commerce/subscriptions/resume

Resume a paused subscription. A next-charge date that fell in the past while paused is re-anchored one interval from now, so resuming never fires an immediate backlog of missed cycles.

string

string (enum: true|false)

object

required

Serializable recurring subscription schedule snapshot. The renewal reuses the stored agent-payment-mandate authorization; the caller round-trips this snapshot in each request body.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/subscriptions/resume" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "subscription": {}
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/subscriptions/resume', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "subscription": {}
}),
})
console.log(await res.json())

{
  "data": {
    "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
    "cartId": "string",
    "principalId": "string",
    "mandateId": "string",
    "channel": "whatsapp",
    "items": [
      {
        "productRetailerId": "string",
        "name": null,
        "quantity": 0,
        "unitPrice": 0,
        "currency": "string"
      }
    ],
    "currency": "string",
    "amount": 0,
    "interval": "weekly",
    "status": "active",
    "cyclesCompleted": 0,
    "nextChargeAt": null,
    "lastRenewalAt": null,
    "lastRenewalReference": null,
    "createdAt": 0,
    "updatedAt": 0,
    "pausedAt": null,
    "canceledAt": null
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Open a UCP cart session

POST /api/v1/commerce/ucp/cart

Open a UCP cart session, pricing the agent’s requested items SERVER-SIDE against the merchant catalog. Unknown / out-of-stock / wrong-currency lines are surfaced as blocking messages and keep the cart not_ready_for_payment. Design-partner pilot — gated behind a per-tenant flag.

string

string (enum: true|false)

string

required

—

string

required

—

object[]

required

—

object[]

required

—

string | null

—

string | null

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/ucp/cart" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "string",
  "merchantId": "string",
  "items": [],
  "catalog": []
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/ucp/cart', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "id": "string",
  "merchantId": "string",
  "items": [],
  "catalog": []
}),
})
console.log(await res.json())

{
  "data": {
    "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
    "merchantId": "string",
    "status": "not_ready_for_payment",
    "currency": "string",
    "category": null,
    "lineItems": [
      {
        "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
        "productId": "string",
        "title": null,
        "quantity": 0,
        "unitPrice": 0,
        "currency": "string",
        "lineTotal": 0
      }
    ],
    "itemCount": 0,
    "subtotal": 0,
    "total": 0,
    "messages": [
      {
        "type": "error",
        "code": "string",
        "productId": null,
        "message": "string"
      }
    ],
    "order": null,
    "createdAt": 0,
    "updatedAt": 0
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Complete a UCP cart under a signed mandate

POST /api/v1/commerce/ucp/cart/complete

Complete a ready_for_payment UCP cart session under an AP2 payment mandate. The session is re-priced SERVER-SIDE against the supplied catalog first (the incoming total is never trusted), then that re-priced total is charged against the mandate (consent digest + spend caps re-verified); a charge outside the mandate is rejected with VALIDATION_ERROR so an agent can never spend past signed consent. Authorizes the buy only — no money moves and nothing is sent (invariant #45). Design-partner pilot — gated behind a per-tenant flag.

string

string (enum: true|false)

object

required

Serializable ACP checkout-session snapshot. Totals are re-derived server-side from the catalog and never trusted from the wire. Amounts are in MAJOR currency units.

object[]

required

—

object

required

Serializable AP2-style payment mandate snapshot. Carries a SHA-256 consent digest re-verified before every spend.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/ucp/cart/complete" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "session": {},
  "catalog": [],
  "mandate": {}
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/ucp/cart/complete', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "session": {},
  "catalog": [],
  "mandate": {}
}),
})
console.log(await res.json())

{
  "data": {
    "session": {
      "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
      "merchantId": "string",
      "status": "not_ready_for_payment",
      "currency": "string",
      "category": null,
      "lineItems": [
        {
          "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
          "productId": "string",
          "title": null,
          "quantity": 0,
          "unitPrice": 0,
          "currency": "string",
          "lineTotal": 0
        }
      ],
      "itemCount": 0,
      "subtotal": 0,
      "total": 0,
      "messages": [
        {
          "type": "error",
          "code": "string",
          "productId": null,
          "message": "string"
        }
      ],
      "order": null,
      "createdAt": 0,
      "updatedAt": 0
    },
    "mandate": {
      "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
      "agentId": "string",
      "principalId": "string",
      "maxPerTransaction": 0,
      "totalCap": 0,
      "currency": "string",
      "allowedMerchants": [
        "string"
      ],
      "allowedCategories": [
        "string"
      ],
      "spent": 0,
      "authorizationCount": 0,
      "status": "active",
      "consentDigest": "string",
      "expiresAt": null,
      "createdAt": 0,
      "updatedAt": 0,
      "revokedAt": null
    },
    "authorization": {
      "authorized": false,
      "reason": "string",
      "authorizationId": "string",
      "remainingCap": 0,
      "settlement": null
    }
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Re-price a UCP cart session

POST /api/v1/commerce/ucp/cart/update

Re-price a UCP cart session for a new requested-item set (replace-items semantics) and re-derive its status. A completed / canceled session is immutable and rejected with VALIDATION_ERROR. Design-partner pilot — gated behind a per-tenant flag.

string

string (enum: true|false)

object

required

Serializable ACP checkout-session snapshot. Totals are re-derived server-side from the catalog and never trusted from the wire. Amounts are in MAJOR currency units.

object[]

required

—

object[]

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/ucp/cart/update" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "session": {},
  "items": [],
  "catalog": []
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/ucp/cart/update', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "session": {},
  "items": [],
  "catalog": []
}),
})
console.log(await res.json())

{
  "data": {
    "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
    "merchantId": "string",
    "status": "not_ready_for_payment",
    "currency": "string",
    "category": null,
    "lineItems": [
      {
        "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
        "productId": "string",
        "title": null,
        "quantity": 0,
        "unitPrice": 0,
        "currency": "string",
        "lineTotal": 0
      }
    ],
    "itemCount": 0,
    "subtotal": 0,
    "total": 0,
    "messages": [
      {
        "type": "error",
        "code": "string",
        "productId": null,
        "message": "string"
      }
    ],
    "order": null,
    "createdAt": 0,
    "updatedAt": 0
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Build the UCP product catalog

POST /api/v1/commerce/ucp/catalog

Normalize a merchant catalog into the UCP product catalog a shopping agent browses to discover what’s for sale (prices in MAJOR currency units; availability defaults to in_stock). Design-partner pilot — gated behind a per-tenant flag.

string

string (enum: true|false)

object[]

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/ucp/catalog" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "products": []
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/ucp/catalog', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "products": []
}),
})
console.log(await res.json())

{
  "data": {
    "protocol": "string",
    "protocolVersion": "string",
    "count": 0,
    "items": [
      {
        "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
        "title": "string",
        "description": null,
        "price": 0,
        "currency": "string",
        "availability": "in_stock",
        "inventoryQuantity": null,
        "link": null,
        "category": null
      }
    ],
    "generatedAt": 0
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Build the UCP storefront manifest

POST /api/v1/commerce/ucp/manifest

Build the UCP (Universal Commerce Protocol) discovery manifest a merchant publishes for UCP-native shopping agents: protocol version, capabilities, accepted payment methods, and endpoint paths. Design-partner pilot — gated behind a per-tenant flag.

string

string (enum: true|false)

string

required

—

string

required

—

string

required

https origin the merchant’s UCP endpoints are served from.

string

required

—

array | null

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/ucp/manifest" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "merchantId": "string",
  "merchantName": "string",
  "baseUrl": "string",
  "currency": "string"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/ucp/manifest', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "merchantId": "string",
  "merchantName": "string",
  "baseUrl": "string",
  "currency": "string"
}),
})
console.log(await res.json())

{
  "data": {
    "protocol": "string",
    "protocolVersion": "string",
    "merchant": {
      "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
      "name": "string",
      "currency": "string",
      "categories": [
        "string"
      ]
    },
    "capabilities": {},
    "paymentMethods": [
      "string"
    ],
    "endpoints": {},
    "generatedAt": 0
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Resolve an in-conversation web-chat checkout

POST /api/v1/commerce/webchat-checkout

Resolve a PCI-safe embedded tokenized checkout (where the tenant has configured client-side tokenization) or the hosted pay link, both anchored to one PaymentRequest snapshot.

string

string (enum: true|false)

object

required

—

object

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/webchat-checkout" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "order": {},
  "config": {}
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/webchat-checkout', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "order": {},
  "config": {}
}),
})
console.log(await res.json())

{
  "data": {
    "method": "string",
    "currency": "string",
    "subtotal": 0,
    "paymentRequest": {
      "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
      "amount": 0,
      "currency": "string",
      "description": null,
      "reference": null,
      "checkoutUrl": "string",
      "status": "pending",
      "expiresAt": null,
      "createdAt": 0,
      "updatedAt": 0
    }
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Resolve an in-thread WhatsApp checkout

POST /api/v1/commerce/whatsapp-checkout

Resolve native WhatsApp Pay (where Meta supports it) or the hosted pay link, both anchored to one PaymentRequest snapshot.

string

string (enum: true|false)

object

required

—

object

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/commerce/whatsapp-checkout" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "order": {},
  "config": {}
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/whatsapp-checkout', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "order": {},
  "config": {}
}),
})
console.log(await res.json())

{
  "data": {
    "method": "string",
    "rails": [
      "string"
    ],
    "currency": "string"
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Publish/replace the public ACP storefront config

PUT /api/v1/commerce/agentic/storefront

Create or replace this tenant’s STORED, agent-facing ACP storefront config so a third-party AI shopping agent (ChatGPT Instant Checkout / Perplexity / AP2) can discover and drive it with no Orbit credential. Once enabled, the public edge serves the discovery manifest + product feed at the returned publicUrl and prices checkouts SERVER-SIDE against the stored catalog. The catalog is bounded (max 250 products). No money moves and nothing is sent (invariant #45).

string

string (enum: true|false)

boolean

—

string

required

—

string

required

—

string[]

—

object[]

—

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/commerce/agentic/storefront" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "merchantName": "string",
  "currency": "string"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/commerce/agentic/storefront', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "merchantName": "string",
  "currency": "string"
}),
})
console.log(await res.json())

{
  "data": {
    "storefrontId": "string",
    "publicUrl": "string",
    "published": false,
    "productCount": 0
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

​Commerce API

​title: “Errors worth branching on” description: “Per-endpoint failure templates matching the envelope — what actually fires, what to retry, what to surface to the operator.”

​Errors worth branching on

​401 — Unauthorized

​403 — Forbidden

​422 — Schema

​429 — Rate

​409 — Conflict

​60-second retry matrix

​Read the stored public ACP storefront config

​Issue an agent payment mandate

​Dry-run authorize a charge against a mandate

​Authorize and commit a charge

​Mint a card-network agent payment token or trusted-agent credential

​Revoke a mandate

​Verify mandate integrity

​Open an ACP checkout session

​Complete an ACP checkout under a signed mandate

​Re-price an ACP checkout session

​Build the ACP product feed

​Build the ACP storefront manifest

​Resolve an in-thread Apple Messages for Business checkout

​Create cart

​Check whether the cart is abandoned

​Select checkout-channel preference order

​Merge a channel contribution into the cart

​Reconcile a cross-channel payment against the cart

​Advance the checkout state machine

​Initiate a DCB charge

​Capture a DCB charge

​Record a DCB chargeback

​Fail a DCB charge

​Refund a DCB charge

​Configure a DCB merchant

​Build the carrier-billing operator request

​Reconcile a DCB settlement

​Open an MPP pre-authorized session

​Meter and settle one call streamed against an MPP session

​Dry-run meter a call against an MPP session

​Revoke an MPP session

​Verify MPP session integrity

​Mint a hosted pay-by-link

​Reconcile a captured PSP payment

​Render a pay-by-link for one channel

​Advance a pay-by-link lifecycle

​Resolve an in-thread RCS checkout

​Bind an in-call PCI capture to a commerce charge

​Start a recurring subscription

​Cancel a subscription

​Annotate + sort a set of subscriptions

​Pause a subscription

​Fire a due subscription renewal cycle

​Resume a paused subscription

​Open a UCP cart session

​Complete a UCP cart under a signed mandate

​Re-price a UCP cart session

​Build the UCP product catalog

​Build the UCP storefront manifest

​Resolve an in-conversation web-chat checkout

​Resolve an in-thread WhatsApp checkout

​Publish/replace the public ACP storefront config

Commerce API

title: “Errors worth branching on” description: “Per-endpoint failure templates matching the envelope — what actually fires, what to retry, what to surface to the operator.”

Errors worth branching on

401 — Unauthorized

403 — Forbidden

422 — Schema

429 — Rate

409 — Conflict

60-second retry matrix

Read the stored public ACP storefront config

Issue an agent payment mandate

Dry-run authorize a charge against a mandate

Authorize and commit a charge

Mint a card-network agent payment token or trusted-agent credential

Revoke a mandate

Verify mandate integrity

Open an ACP checkout session

Complete an ACP checkout under a signed mandate

Re-price an ACP checkout session

Build the ACP product feed

Build the ACP storefront manifest

Resolve an in-thread Apple Messages for Business checkout

Create cart

Check whether the cart is abandoned

Select checkout-channel preference order

Merge a channel contribution into the cart

Reconcile a cross-channel payment against the cart

Advance the checkout state machine

Initiate a DCB charge

Capture a DCB charge

Record a DCB chargeback

Fail a DCB charge

Refund a DCB charge

Configure a DCB merchant

Build the carrier-billing operator request

Reconcile a DCB settlement

Open an MPP pre-authorized session

Meter and settle one call streamed against an MPP session

Dry-run meter a call against an MPP session

Revoke an MPP session

Verify MPP session integrity

Mint a hosted pay-by-link

Reconcile a captured PSP payment

Render a pay-by-link for one channel

Advance a pay-by-link lifecycle

Resolve an in-thread RCS checkout

Bind an in-call PCI capture to a commerce charge

Start a recurring subscription

Cancel a subscription

Annotate + sort a set of subscriptions

Pause a subscription

Fire a due subscription renewal cycle

Resume a paused subscription

Open a UCP cart session

Complete a UCP cart under a signed mandate

Re-price a UCP cart session

Build the UCP product catalog

Build the UCP storefront manifest

Resolve an in-conversation web-chat checkout

Resolve an in-thread WhatsApp checkout

Publish/replace the public ACP storefront config