Get a transaction

curl --request GET \
  --url https://api.sapiom.ai/v1/transactions/{transactionId} \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.sapiom.ai/v1/transactions/{transactionId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sapiom.ai/v1/transactions/{transactionId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sapiom.ai/v1/transactions/{transactionId}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.sapiom.ai/v1/transactions/{transactionId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

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

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "tenantId": "123e4567-e89b-12d3-a456-426614174000",
  "serviceName": "openai",
  "actionName": "completion",
  "resourceName": "gpt-4",
  "status": "authorized",
  "requiresPayment": true,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z",
  "returnUrl": "<string>",
  "nextAction": {},
  "purchase": {
    "type": "ucp_checkout",
    "assertedBy": "merchant",
    "merchant": {
      "origin": "https://shop.example"
    },
    "total": {
      "amount": "19.99",
      "currency": "USD"
    },
    "lineItems": [
      {
        "title": "Mug",
        "itemId": "item_123",
        "quantity": 1,
        "unitAmount": "19.99"
      }
    ],
    "revision": 1
  },
  "order": {},
  "version": "<string>",
  "approvals": {},
  "serviceId": "123e4567-e89b-12d3-a456-426614174000",
  "qualifiers": {
    "model": "gpt-4",
    "tokens": 1000
  },
  "metadata": {},
  "authorizedAt": "2024-01-01T00:00:00.000Z",
  "completedAt": "2024-01-01T00:00:00.000Z",
  "outcome": "success",
  "currentPaymentTransactionId": "123e4567-e89b-12d3-a456-426614174000",
  "payment": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "transactionId": "123e4567-e89b-12d3-a456-426614174000",
    "fiatAmount": "<string>",
    "status": "authorized",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z",
    "fundingSource": "external_card",
    "paymentCardId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "credentialRoute": "real_card_number",
    "placeholder": {
      "number": "4000123412341234",
      "expMonth": 7,
      "expYear": 2029,
      "cvc": "123",
      "brand": "visa",
      "expiresAt": "2026-10-13T13:00:00.000Z",
      "injectionRef": "<string>",
      "transactionId": "<string>"
    },
    "reason": "sapiom_error",
    "authorizedAt": "2024-01-01T00:00:00.000Z"
  },
  "trace": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "externalId": "checkout-session-abc123"
  },
  "agentId": "123e4567-e89b-12d3-a456-426614174000",
  "agent": {
    "id": "<string>",
    "tenantId": "<string>",
    "label": "<string>",
    "name": "<string>",
    "status": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "description": "<string>"
  }
}

GET

transactions

{transactionId}

Get a transaction

curl --request GET \
  --url https://api.sapiom.ai/v1/transactions/{transactionId} \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.sapiom.ai/v1/transactions/{transactionId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sapiom.ai/v1/transactions/{transactionId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sapiom.ai/v1/transactions/{transactionId}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.sapiom.ai/v1/transactions/{transactionId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

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

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "tenantId": "123e4567-e89b-12d3-a456-426614174000",
  "serviceName": "openai",
  "actionName": "completion",
  "resourceName": "gpt-4",
  "status": "authorized",
  "requiresPayment": true,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z",
  "returnUrl": "<string>",
  "nextAction": {},
  "purchase": {
    "type": "ucp_checkout",
    "assertedBy": "merchant",
    "merchant": {
      "origin": "https://shop.example"
    },
    "total": {
      "amount": "19.99",
      "currency": "USD"
    },
    "lineItems": [
      {
        "title": "Mug",
        "itemId": "item_123",
        "quantity": 1,
        "unitAmount": "19.99"
      }
    ],
    "revision": 1
  },
  "order": {},
  "version": "<string>",
  "approvals": {},
  "serviceId": "123e4567-e89b-12d3-a456-426614174000",
  "qualifiers": {
    "model": "gpt-4",
    "tokens": 1000
  },
  "metadata": {},
  "authorizedAt": "2024-01-01T00:00:00.000Z",
  "completedAt": "2024-01-01T00:00:00.000Z",
  "outcome": "success",
  "currentPaymentTransactionId": "123e4567-e89b-12d3-a456-426614174000",
  "payment": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "transactionId": "123e4567-e89b-12d3-a456-426614174000",
    "fiatAmount": "<string>",
    "status": "authorized",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z",
    "fundingSource": "external_card",
    "paymentCardId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "credentialRoute": "real_card_number",
    "placeholder": {
      "number": "4000123412341234",
      "expMonth": 7,
      "expYear": 2029,
      "cvc": "123",
      "brand": "visa",
      "expiresAt": "2026-10-13T13:00:00.000Z",
      "injectionRef": "<string>",
      "transactionId": "<string>"
    },
    "reason": "sapiom_error",
    "authorizedAt": "2024-01-01T00:00:00.000Z"
  },
  "trace": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "externalId": "checkout-session-abc123"
  },
  "agentId": "123e4567-e89b-12d3-a456-426614174000",
  "agent": {
    "id": "<string>",
    "tenantId": "<string>",
    "label": "<string>",
    "name": "<string>",
    "status": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "description": "<string>"
  }
}

Authorizations

x-api-key

string

header

required

Your platform key for buyer management, or a buyer key for everything else.

Path Parameters

transactionId

string

required

Transaction ID

Query Parameters

maxWaitSeconds

string

Wait up to this many seconds (0 to 25) while the transaction is being decided (pending or preparing), answering as soon as it is not; waiting_approval answers at once, since a person must act. Stops if the client goes away. Default 0. A purchase is waited on until its nextAction is not wait, or, given since, until its version differs.

since

string

With maxWaitSeconds: a purchase version from an earlier read; the wait answers as soon as the purchase has changed from it.

Response

Transaction retrieved successfully

string

required

Transaction ID

Example:

"123e4567-e89b-12d3-a456-426614174000"

tenantId

string

required

Organization ID

Example:

"123e4567-e89b-12d3-a456-426614174000"

serviceName

string

required

Service identifier

Example:

"openai"

actionName

string

required

Action being performed

Example:

"completion"

resourceName

string

required

Resource being accessed

Example:

"gpt-4"

status

enum<string>

required

Transaction status

Available options:

pending,

preparing,

waiting_approval,

authorized,

completed,

denied,

cancelled,

needs_revision

Example:

"authorized"

requiresPayment

boolean

required

Whether the transaction requires payment

Example:

true

createdAt

string<date-time>

required

Creation timestamp

Example:

"2024-01-01T00:00:00.000Z"

updatedAt

string<date-time>

required

Last update timestamp

Example:

"2024-01-01T00:00:00.000Z"

returnUrl

string | null

Integrator-provided return destination for hosted transaction steps

nextAction

object

The next step in one vocabulary (type + actor: wait, buyer_security_code, approval, payment_ready, closed, …), always present for a purchase. For a transaction that buys nothing, only an approval or security-code step, absent when nobody needs to act. Links are derived at read time.

purchase

object

For a purchase: what is bought, from whom, for how much, and who said so (assertedBy: merchant for the merchant's own checkout answer, agent for the agent's unchecked statement). Read from durable records; absent for a transaction that buys nothing.

Example:

{
  "type": "ucp_checkout",
  "assertedBy": "merchant",
  "merchant": { "origin": "https://shop.example" },
  "total": { "amount": "19.99", "currency": "USD" },
  "lineItems": [
    {
      "title": "Mug",
      "itemId": "item_123",
      "quantity": 1,
      "unitAmount": "19.99"
    }
  ],
  "revision": 1
}

order

object | null

For a purchase: the merchant-confirmed order outcome (confirmed, not_confirmed, unknown). Null for a browser purchase, which has no order confirmation.

version

string

For a purchase: changes whenever anything the caller acts on changes. Pass it back as since to wait for the next change.

approvals

object

Approval obligations and linked successor attempts; inspect an approval for current authority

serviceId

string | null

Service entity ID (foreign key reference)

Example:

"123e4567-e89b-12d3-a456-426614174000"

qualifiers

object

Additional qualifiers for the transaction

Example:

{ "model": "gpt-4", "tokens": 1000 }

metadata

object

Additional metadata for the transaction

authorizedAt

string<date-time>

Authorization timestamp

Example:

"2024-01-01T00:00:00.000Z"

completedAt

string<date-time>

Completion timestamp

Example:

"2024-01-01T00:00:00.000Z"

outcome

enum<string>

Transaction outcome (set when completed)

Available options:

success,

error

Example:

"success"

currentPaymentTransactionId

string | null

Current payment transaction ID if transaction requires payment

Example:

"123e4567-e89b-12d3-a456-426614174000"

payment

object

Payment transaction details when transaction requires payment

Show child attributes

trace

object

Trace information for workflow grouping

Show child attributes

agentId

string | null

Agent ID if transaction is associated with an agent

Example:

"123e4567-e89b-12d3-a456-426614174000"

agent

object

Agent information if transaction is associated with an agent

Show child attributes

Overview

REST API

MCP and SDK

Errors

Get a transaction

Authorizations

Path Parameters

Query Parameters

Response