Create a transaction
curl --request POST \
--url https://api.sapiom.ai/v1/transactions \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--header 'x-idempotency-key: <x-idempotency-key>' \
--data '
{
"requestFacts": {
"source": "ucp-checkout",
"version": "v1",
"sdk": {},
"request": {
"merchantOrigin": "https://shop.example",
"estimate": {
"amount": "248.00",
"currency": "USD"
}
}
},
"funding": {
"source": "external_card",
"paymentCardId": "00000000-0000-4000-8000-000000000001"
}
}
'import requests
url = "https://api.sapiom.ai/v1/transactions"
payload = {
"requestFacts": {
"source": "ucp-checkout",
"version": "v1",
"sdk": {},
"request": {
"merchantOrigin": "https://shop.example",
"estimate": {
"amount": "248.00",
"currency": "USD"
}
}
},
"funding": {
"source": "external_card",
"paymentCardId": "00000000-0000-4000-8000-000000000001"
}
}
headers = {
"x-idempotency-key": "<x-idempotency-key>",
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'x-idempotency-key': '<x-idempotency-key>',
'x-api-key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
requestFacts: {
source: 'ucp-checkout',
version: 'v1',
sdk: {},
request: {
merchantOrigin: 'https://shop.example',
estimate: {amount: '248.00', currency: 'USD'}
}
},
funding: {source: 'external_card', paymentCardId: '00000000-0000-4000-8000-000000000001'}
})
};
fetch('https://api.sapiom.ai/v1/transactions', 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",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'requestFacts' => [
'source' => 'ucp-checkout',
'version' => 'v1',
'sdk' => [
],
'request' => [
'merchantOrigin' => 'https://shop.example',
'estimate' => [
'amount' => '248.00',
'currency' => 'USD'
]
]
],
'funding' => [
'source' => 'external_card',
'paymentCardId' => '00000000-0000-4000-8000-000000000001'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>",
"x-idempotency-key: <x-idempotency-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"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.sapiom.ai/v1/transactions"
payload := strings.NewReader("{\n \"requestFacts\": {\n \"source\": \"ucp-checkout\",\n \"version\": \"v1\",\n \"sdk\": {},\n \"request\": {\n \"merchantOrigin\": \"https://shop.example\",\n \"estimate\": {\n \"amount\": \"248.00\",\n \"currency\": \"USD\"\n }\n }\n },\n \"funding\": {\n \"source\": \"external_card\",\n \"paymentCardId\": \"00000000-0000-4000-8000-000000000001\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-idempotency-key", "<x-idempotency-key>")
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.sapiom.ai/v1/transactions")
.header("x-idempotency-key", "<x-idempotency-key>")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"requestFacts\": {\n \"source\": \"ucp-checkout\",\n \"version\": \"v1\",\n \"sdk\": {},\n \"request\": {\n \"merchantOrigin\": \"https://shop.example\",\n \"estimate\": {\n \"amount\": \"248.00\",\n \"currency\": \"USD\"\n }\n }\n },\n \"funding\": {\n \"source\": \"external_card\",\n \"paymentCardId\": \"00000000-0000-4000-8000-000000000001\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sapiom.ai/v1/transactions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-idempotency-key"] = '<x-idempotency-key>'
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"requestFacts\": {\n \"source\": \"ucp-checkout\",\n \"version\": \"v1\",\n \"sdk\": {},\n \"request\": {\n \"merchantOrigin\": \"https://shop.example\",\n \"estimate\": {\n \"amount\": \"248.00\",\n \"currency\": \"USD\"\n }\n }\n },\n \"funding\": {\n \"source\": \"external_card\",\n \"paymentCardId\": \"00000000-0000-4000-8000-000000000001\"\n }\n}"
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": {},
"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": "Insufficient funds",
"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>"
}
}Transactions
Create a transaction
Creates a new transaction for the organization associated with the API key. Automatically handles authorization and payment if required. Supports an optional x-idempotency-key header (max 255 chars), unique per tenant: replaying a key returns the previously created transaction — whatever its state — instead of creating a new one. First-write-wins: the original transaction is returned even if the replayed request body differs, so use a fresh key for each genuinely new request. Requires a buyer key.
POST
/
v1
/
transactions
Create a transaction
curl --request POST \
--url https://api.sapiom.ai/v1/transactions \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--header 'x-idempotency-key: <x-idempotency-key>' \
--data '
{
"requestFacts": {
"source": "ucp-checkout",
"version": "v1",
"sdk": {},
"request": {
"merchantOrigin": "https://shop.example",
"estimate": {
"amount": "248.00",
"currency": "USD"
}
}
},
"funding": {
"source": "external_card",
"paymentCardId": "00000000-0000-4000-8000-000000000001"
}
}
'import requests
url = "https://api.sapiom.ai/v1/transactions"
payload = {
"requestFacts": {
"source": "ucp-checkout",
"version": "v1",
"sdk": {},
"request": {
"merchantOrigin": "https://shop.example",
"estimate": {
"amount": "248.00",
"currency": "USD"
}
}
},
"funding": {
"source": "external_card",
"paymentCardId": "00000000-0000-4000-8000-000000000001"
}
}
headers = {
"x-idempotency-key": "<x-idempotency-key>",
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'x-idempotency-key': '<x-idempotency-key>',
'x-api-key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
requestFacts: {
source: 'ucp-checkout',
version: 'v1',
sdk: {},
request: {
merchantOrigin: 'https://shop.example',
estimate: {amount: '248.00', currency: 'USD'}
}
},
funding: {source: 'external_card', paymentCardId: '00000000-0000-4000-8000-000000000001'}
})
};
fetch('https://api.sapiom.ai/v1/transactions', 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",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'requestFacts' => [
'source' => 'ucp-checkout',
'version' => 'v1',
'sdk' => [
],
'request' => [
'merchantOrigin' => 'https://shop.example',
'estimate' => [
'amount' => '248.00',
'currency' => 'USD'
]
]
],
'funding' => [
'source' => 'external_card',
'paymentCardId' => '00000000-0000-4000-8000-000000000001'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>",
"x-idempotency-key: <x-idempotency-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"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.sapiom.ai/v1/transactions"
payload := strings.NewReader("{\n \"requestFacts\": {\n \"source\": \"ucp-checkout\",\n \"version\": \"v1\",\n \"sdk\": {},\n \"request\": {\n \"merchantOrigin\": \"https://shop.example\",\n \"estimate\": {\n \"amount\": \"248.00\",\n \"currency\": \"USD\"\n }\n }\n },\n \"funding\": {\n \"source\": \"external_card\",\n \"paymentCardId\": \"00000000-0000-4000-8000-000000000001\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-idempotency-key", "<x-idempotency-key>")
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.sapiom.ai/v1/transactions")
.header("x-idempotency-key", "<x-idempotency-key>")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"requestFacts\": {\n \"source\": \"ucp-checkout\",\n \"version\": \"v1\",\n \"sdk\": {},\n \"request\": {\n \"merchantOrigin\": \"https://shop.example\",\n \"estimate\": {\n \"amount\": \"248.00\",\n \"currency\": \"USD\"\n }\n }\n },\n \"funding\": {\n \"source\": \"external_card\",\n \"paymentCardId\": \"00000000-0000-4000-8000-000000000001\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sapiom.ai/v1/transactions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-idempotency-key"] = '<x-idempotency-key>'
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"requestFacts\": {\n \"source\": \"ucp-checkout\",\n \"version\": \"v1\",\n \"sdk\": {},\n \"request\": {\n \"merchantOrigin\": \"https://shop.example\",\n \"estimate\": {\n \"amount\": \"248.00\",\n \"currency\": \"USD\"\n }\n }\n },\n \"funding\": {\n \"source\": \"external_card\",\n \"paymentCardId\": \"00000000-0000-4000-8000-000000000001\"\n }\n}"
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": {},
"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": "Insufficient funds",
"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>"
}
}For a Sapiom Pay transaction, send
requestFacts with source: "ucp-checkout", version: "v1" and the merchant’s origin in request.merchantOrigin, plus funding.source: "external_card". Omit funding.paymentCardId to use the buyer’s default card. Then open the merchant checkout with Open the checkout.Authorizations
Your platform key for buyer management, or a buyer key for everything else.
Headers
Body
application/json
For a transaction: source is ucp-checkout, version is v1, and request.merchantOrigin is the merchant's origin. request.estimate is your optional expected total.
Show child attributes
Show child attributes
Example:
{
"source": "ucp-checkout",
"version": "v1",
"sdk": {},
"request": {
"merchantOrigin": "https://shop.example",
"estimate": { "amount": "248.00", "currency": "USD" }
}
}
How a UCP checkout is paid. Each final merchant total is paid with this card, authorized together with governance; the authorized transaction's payment carries the placeholder card to submit. Only for ucp-checkout request facts, and never with paymentData.
Show child attributes
Show child attributes
For one UCP checkout: the shipping address and contact the checkout driver fills into the merchant checkout wherever the agent's create or update leaves them out: the contact and the address's name as buyer, and the address as the destination of a shipping method that has none (or of a new shipping method, when the request has no fulfillment). Anything the agent sends wins. Only for ucp-checkout request facts.
Show child attributes
Show child attributes
Return destination after hosted approval and card confirmation. Must use an origin or app scheme registered by the organization.
Maximum string length:
2048Additional metadata for the transaction
Response
Transaction created successfully
Transaction ID
Example:
"123e4567-e89b-12d3-a456-426614174000"
Organization ID
Example:
"123e4567-e89b-12d3-a456-426614174000"
Service identifier
Example:
"openai"
Action being performed
Example:
"completion"
Resource being accessed
Example:
"gpt-4"
Transaction status
Available options:
pending, preparing, waiting_approval, authorized, completed, denied, cancelled, needs_revision Example:
"authorized"
Whether the transaction requires payment
Example:
true
Creation timestamp
Example:
"2024-01-01T00:00:00.000Z"
Last update timestamp
Example:
"2024-01-01T00:00:00.000Z"
Integrator-provided return destination for hosted transaction steps
Current approval or payment action; its navigation link is derived at read time
Approval obligations and linked successor attempts; inspect an approval for current authority
Service entity ID (foreign key reference)
Example:
"123e4567-e89b-12d3-a456-426614174000"
Additional qualifiers for the transaction
Example:
{ "model": "gpt-4", "tokens": 1000 }
Additional metadata for the transaction
Authorization timestamp
Example:
"2024-01-01T00:00:00.000Z"
Completion timestamp
Example:
"2024-01-01T00:00:00.000Z"
Transaction outcome (set when completed)
Available options:
success, error Example:
"success"
Current payment transaction ID if transaction requires payment
Example:
"123e4567-e89b-12d3-a456-426614174000"
Payment transaction details when transaction requires payment
Show child attributes
Show child attributes
Trace information for workflow grouping
Show child attributes
Show child attributes
Agent ID if transaction is associated with an agent
Example:
"123e4567-e89b-12d3-a456-426614174000"
Agent information if transaction is associated with an agent
Show child attributes
Show child attributes