Create a payment
curl --request POST \
--url https://api.example.com/v2/payments \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--header 'X-Morphosis-Key-Id: <x-morphosis-key-id>' \
--header 'X-Morphosis-Nonce: <x-morphosis-nonce>' \
--header 'X-Morphosis-Signature: <api-key>' \
--header 'X-Morphosis-Signature-Version: <x-morphosis-signature-version>' \
--header 'X-Morphosis-Timestamp: <x-morphosis-timestamp>' \
--data '
{
"external_reference": "merchant-order-20260730-001",
"requested_amount": {
"currency": "USD",
"decimal": "1.00",
"minor_units": "100"
},
"metadata": {
"checkout_session": "checkout-001"
}
}
'import requests
url = "https://api.example.com/v2/payments"
payload = {
"external_reference": "merchant-order-20260730-001",
"requested_amount": {
"currency": "USD",
"decimal": "1.00",
"minor_units": "100"
},
"metadata": { "checkout_session": "checkout-001" }
}
headers = {
"X-Morphosis-Signature-Version": "<x-morphosis-signature-version>",
"X-Morphosis-Key-Id": "<x-morphosis-key-id>",
"X-Morphosis-Timestamp": "<x-morphosis-timestamp>",
"X-Morphosis-Nonce": "<x-morphosis-nonce>",
"X-Morphosis-Signature": "<api-key>",
"Idempotency-Key": "<idempotency-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'X-Morphosis-Signature-Version': '<x-morphosis-signature-version>',
'X-Morphosis-Key-Id': '<x-morphosis-key-id>',
'X-Morphosis-Timestamp': '<x-morphosis-timestamp>',
'X-Morphosis-Nonce': '<x-morphosis-nonce>',
'X-Morphosis-Signature': '<api-key>',
'Idempotency-Key': '<idempotency-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
external_reference: 'merchant-order-20260730-001',
requested_amount: {currency: 'USD', decimal: '1.00', minor_units: '100'},
metadata: {checkout_session: 'checkout-001'}
})
};
fetch('https://api.example.com/v2/payments', 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.example.com/v2/payments",
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([
'external_reference' => 'merchant-order-20260730-001',
'requested_amount' => [
'currency' => 'USD',
'decimal' => '1.00',
'minor_units' => '100'
],
'metadata' => [
'checkout_session' => 'checkout-001'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>",
"X-Morphosis-Key-Id: <x-morphosis-key-id>",
"X-Morphosis-Nonce: <x-morphosis-nonce>",
"X-Morphosis-Signature: <api-key>",
"X-Morphosis-Signature-Version: <x-morphosis-signature-version>",
"X-Morphosis-Timestamp: <x-morphosis-timestamp>"
],
]);
$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.example.com/v2/payments"
payload := strings.NewReader("{\n \"external_reference\": \"merchant-order-20260730-001\",\n \"requested_amount\": {\n \"currency\": \"USD\",\n \"decimal\": \"1.00\",\n \"minor_units\": \"100\"\n },\n \"metadata\": {\n \"checkout_session\": \"checkout-001\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Morphosis-Signature-Version", "<x-morphosis-signature-version>")
req.Header.Add("X-Morphosis-Key-Id", "<x-morphosis-key-id>")
req.Header.Add("X-Morphosis-Timestamp", "<x-morphosis-timestamp>")
req.Header.Add("X-Morphosis-Nonce", "<x-morphosis-nonce>")
req.Header.Add("X-Morphosis-Signature", "<api-key>")
req.Header.Add("Idempotency-Key", "<idempotency-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.example.com/v2/payments")
.header("X-Morphosis-Signature-Version", "<x-morphosis-signature-version>")
.header("X-Morphosis-Key-Id", "<x-morphosis-key-id>")
.header("X-Morphosis-Timestamp", "<x-morphosis-timestamp>")
.header("X-Morphosis-Nonce", "<x-morphosis-nonce>")
.header("X-Morphosis-Signature", "<api-key>")
.header("Idempotency-Key", "<idempotency-key>")
.header("Content-Type", "application/json")
.body("{\n \"external_reference\": \"merchant-order-20260730-001\",\n \"requested_amount\": {\n \"currency\": \"USD\",\n \"decimal\": \"1.00\",\n \"minor_units\": \"100\"\n },\n \"metadata\": {\n \"checkout_session\": \"checkout-001\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v2/payments")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Morphosis-Signature-Version"] = '<x-morphosis-signature-version>'
request["X-Morphosis-Key-Id"] = '<x-morphosis-key-id>'
request["X-Morphosis-Timestamp"] = '<x-morphosis-timestamp>'
request["X-Morphosis-Nonce"] = '<x-morphosis-nonce>'
request["X-Morphosis-Signature"] = '<api-key>'
request["Idempotency-Key"] = '<idempotency-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"external_reference\": \"merchant-order-20260730-001\",\n \"requested_amount\": {\n \"currency\": \"USD\",\n \"decimal\": \"1.00\",\n \"minor_units\": \"100\"\n },\n \"metadata\": {\n \"checkout_session\": \"checkout-001\"\n }\n}"
response = http.request(request)
puts response.read_body{
"payment_id": "pay_01K1DRAFT8F7Z6K5Q4N3M2P1A0",
"requested_amount": {
"currency": "USD",
"decimal": "1.00",
"minor_units": "100"
},
"payment_instructions": {
"network": "tron_shasta",
"asset": "TRX",
"destination": "TDocs0nlyAddressNotForPayments0000",
"amount": {
"currency": "USD",
"decimal": "1.00",
"minor_units": "100"
},
"expires_at": "2026-07-30T15:40:00Z"
},
"environment": "sandbox",
"created_at": "2026-07-30T15:10:00Z",
"updated_at": "2026-07-30T15:12:30Z",
"external_reference": "merchant-order-20260730-001",
"metadata": {
"checkout_session": "checkout-001"
}
}{
"payment_id": "pay_01K1DRAFT8F7Z6K5Q4N3M2P1A0",
"requested_amount": {
"currency": "USD",
"decimal": "1.00",
"minor_units": "100"
},
"environment": "sandbox",
"created_at": "2026-07-30T15:10:00Z",
"updated_at": "2026-07-30T15:12:30Z",
"external_reference": "merchant-order-20260730-001",
"payment_instructions": {
"network": "tron_shasta",
"asset": "TRX",
"destination": "TDocs0nlyAddressNotForPayments0000",
"amount": {
"currency": "USD",
"decimal": "1.00",
"minor_units": "100"
},
"expires_at": "2026-07-30T15:40:00Z"
},
"metadata": {
"checkout_session": "checkout-001"
}
}{
"type": "urn:morphosisblock:payment:error:invalid-request",
"title": "Invalid request",
"status": 400,
"code": "invalid_request",
"detail": "One or more request fields are invalid.",
"request_id": "req_01K1DRAFT8F7Z6K5Q4N3M2P1A0"
}{
"type": "urn:morphosisblock:payment:error:authentication-failed",
"title": "Authentication failed",
"status": 401,
"code": "authentication_failed",
"detail": "The request signature could not be verified.",
"request_id": "req_01K1DRAFT8F7Z6K5Q4N3M2P1A0"
}{
"type": "urn:morphosisblock:payment:error:idempotency-conflict",
"title": "Idempotency conflict",
"status": 409,
"code": "idempotency_conflict",
"detail": "The idempotency key is already bound to different content.",
"request_id": "req_01K1DRAFT8F7Z6K5Q4N3M2P1A0"
}{
"type": "urn:morphosisblock:payment:error:payment-denied",
"title": "Payment denied",
"status": 422,
"code": "payment_denied",
"detail": "The payment cannot proceed under a business rule.",
"request_id": "req_01K1DRAFT8F7Z6K5Q4N3M2P1A0"
}API reference
Create a payment
Draft API Preview for POST /v2/payments.
Create a payment
curl --request POST \
--url https://api.example.com/v2/payments \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--header 'X-Morphosis-Key-Id: <x-morphosis-key-id>' \
--header 'X-Morphosis-Nonce: <x-morphosis-nonce>' \
--header 'X-Morphosis-Signature: <api-key>' \
--header 'X-Morphosis-Signature-Version: <x-morphosis-signature-version>' \
--header 'X-Morphosis-Timestamp: <x-morphosis-timestamp>' \
--data '
{
"external_reference": "merchant-order-20260730-001",
"requested_amount": {
"currency": "USD",
"decimal": "1.00",
"minor_units": "100"
},
"metadata": {
"checkout_session": "checkout-001"
}
}
'import requests
url = "https://api.example.com/v2/payments"
payload = {
"external_reference": "merchant-order-20260730-001",
"requested_amount": {
"currency": "USD",
"decimal": "1.00",
"minor_units": "100"
},
"metadata": { "checkout_session": "checkout-001" }
}
headers = {
"X-Morphosis-Signature-Version": "<x-morphosis-signature-version>",
"X-Morphosis-Key-Id": "<x-morphosis-key-id>",
"X-Morphosis-Timestamp": "<x-morphosis-timestamp>",
"X-Morphosis-Nonce": "<x-morphosis-nonce>",
"X-Morphosis-Signature": "<api-key>",
"Idempotency-Key": "<idempotency-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'X-Morphosis-Signature-Version': '<x-morphosis-signature-version>',
'X-Morphosis-Key-Id': '<x-morphosis-key-id>',
'X-Morphosis-Timestamp': '<x-morphosis-timestamp>',
'X-Morphosis-Nonce': '<x-morphosis-nonce>',
'X-Morphosis-Signature': '<api-key>',
'Idempotency-Key': '<idempotency-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
external_reference: 'merchant-order-20260730-001',
requested_amount: {currency: 'USD', decimal: '1.00', minor_units: '100'},
metadata: {checkout_session: 'checkout-001'}
})
};
fetch('https://api.example.com/v2/payments', 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.example.com/v2/payments",
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([
'external_reference' => 'merchant-order-20260730-001',
'requested_amount' => [
'currency' => 'USD',
'decimal' => '1.00',
'minor_units' => '100'
],
'metadata' => [
'checkout_session' => 'checkout-001'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>",
"X-Morphosis-Key-Id: <x-morphosis-key-id>",
"X-Morphosis-Nonce: <x-morphosis-nonce>",
"X-Morphosis-Signature: <api-key>",
"X-Morphosis-Signature-Version: <x-morphosis-signature-version>",
"X-Morphosis-Timestamp: <x-morphosis-timestamp>"
],
]);
$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.example.com/v2/payments"
payload := strings.NewReader("{\n \"external_reference\": \"merchant-order-20260730-001\",\n \"requested_amount\": {\n \"currency\": \"USD\",\n \"decimal\": \"1.00\",\n \"minor_units\": \"100\"\n },\n \"metadata\": {\n \"checkout_session\": \"checkout-001\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Morphosis-Signature-Version", "<x-morphosis-signature-version>")
req.Header.Add("X-Morphosis-Key-Id", "<x-morphosis-key-id>")
req.Header.Add("X-Morphosis-Timestamp", "<x-morphosis-timestamp>")
req.Header.Add("X-Morphosis-Nonce", "<x-morphosis-nonce>")
req.Header.Add("X-Morphosis-Signature", "<api-key>")
req.Header.Add("Idempotency-Key", "<idempotency-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.example.com/v2/payments")
.header("X-Morphosis-Signature-Version", "<x-morphosis-signature-version>")
.header("X-Morphosis-Key-Id", "<x-morphosis-key-id>")
.header("X-Morphosis-Timestamp", "<x-morphosis-timestamp>")
.header("X-Morphosis-Nonce", "<x-morphosis-nonce>")
.header("X-Morphosis-Signature", "<api-key>")
.header("Idempotency-Key", "<idempotency-key>")
.header("Content-Type", "application/json")
.body("{\n \"external_reference\": \"merchant-order-20260730-001\",\n \"requested_amount\": {\n \"currency\": \"USD\",\n \"decimal\": \"1.00\",\n \"minor_units\": \"100\"\n },\n \"metadata\": {\n \"checkout_session\": \"checkout-001\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v2/payments")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Morphosis-Signature-Version"] = '<x-morphosis-signature-version>'
request["X-Morphosis-Key-Id"] = '<x-morphosis-key-id>'
request["X-Morphosis-Timestamp"] = '<x-morphosis-timestamp>'
request["X-Morphosis-Nonce"] = '<x-morphosis-nonce>'
request["X-Morphosis-Signature"] = '<api-key>'
request["Idempotency-Key"] = '<idempotency-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"external_reference\": \"merchant-order-20260730-001\",\n \"requested_amount\": {\n \"currency\": \"USD\",\n \"decimal\": \"1.00\",\n \"minor_units\": \"100\"\n },\n \"metadata\": {\n \"checkout_session\": \"checkout-001\"\n }\n}"
response = http.request(request)
puts response.read_body{
"payment_id": "pay_01K1DRAFT8F7Z6K5Q4N3M2P1A0",
"requested_amount": {
"currency": "USD",
"decimal": "1.00",
"minor_units": "100"
},
"payment_instructions": {
"network": "tron_shasta",
"asset": "TRX",
"destination": "TDocs0nlyAddressNotForPayments0000",
"amount": {
"currency": "USD",
"decimal": "1.00",
"minor_units": "100"
},
"expires_at": "2026-07-30T15:40:00Z"
},
"environment": "sandbox",
"created_at": "2026-07-30T15:10:00Z",
"updated_at": "2026-07-30T15:12:30Z",
"external_reference": "merchant-order-20260730-001",
"metadata": {
"checkout_session": "checkout-001"
}
}{
"payment_id": "pay_01K1DRAFT8F7Z6K5Q4N3M2P1A0",
"requested_amount": {
"currency": "USD",
"decimal": "1.00",
"minor_units": "100"
},
"environment": "sandbox",
"created_at": "2026-07-30T15:10:00Z",
"updated_at": "2026-07-30T15:12:30Z",
"external_reference": "merchant-order-20260730-001",
"payment_instructions": {
"network": "tron_shasta",
"asset": "TRX",
"destination": "TDocs0nlyAddressNotForPayments0000",
"amount": {
"currency": "USD",
"decimal": "1.00",
"minor_units": "100"
},
"expires_at": "2026-07-30T15:40:00Z"
},
"metadata": {
"checkout_session": "checkout-001"
}
}{
"type": "urn:morphosisblock:payment:error:invalid-request",
"title": "Invalid request",
"status": 400,
"code": "invalid_request",
"detail": "One or more request fields are invalid.",
"request_id": "req_01K1DRAFT8F7Z6K5Q4N3M2P1A0"
}{
"type": "urn:morphosisblock:payment:error:authentication-failed",
"title": "Authentication failed",
"status": 401,
"code": "authentication_failed",
"detail": "The request signature could not be verified.",
"request_id": "req_01K1DRAFT8F7Z6K5Q4N3M2P1A0"
}{
"type": "urn:morphosisblock:payment:error:idempotency-conflict",
"title": "Idempotency conflict",
"status": 409,
"code": "idempotency_conflict",
"detail": "The idempotency key is already bound to different content.",
"request_id": "req_01K1DRAFT8F7Z6K5Q4N3M2P1A0"
}{
"type": "urn:morphosisblock:payment:error:payment-denied",
"title": "Payment denied",
"status": 422,
"code": "payment_denied",
"detail": "The payment cannot proceed under a business rule.",
"request_id": "req_01K1DRAFT8F7Z6K5Q4N3M2P1A0"
}Draft API Preview for the MorphosisBlock Payment API. This operation is a
contract proposal. It is not a live merchant endpoint.
Authorizations
Morphosis HMAC v1 request authentication. Every API request includes
the five X-Morphosis-* headers documented on each operation.
Build the canonical string by joining these values with newline characters:
v1- Uppercase HTTP method
- Request path and query string
- Unix timestamp in seconds
- Unique nonce
- Base64url-encoded SHA-256 digest of the exact request body bytes
Sign the UTF-8 canonical string with HMAC-SHA-256 and encode the result using unpadded base64url.
Headers
Signature contract version.
Allowed value:
"v1"Public identifier for the merchant signing key.
Required string length:
1 - 128Pattern:
^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$Unix timestamp in whole seconds.
Pattern:
^[0-9]{10}$Unique, single-use request nonce.
Required string length:
16 - 128Pattern:
^[A-Za-z0-9._~-]+$Unpadded base64url HMAC-SHA-256 signature.
Pattern:
^[A-Za-z0-9_-]{43}$Merchant-generated identifier for one logical payment creation. Keep the key unchanged when safely repeating the same HTTP request.
Required string length:
16 - 128Pattern:
^[A-Za-z0-9][A-Za-z0-9._~-]{15,127}$Body
application/json
An exact monetary amount represented without floating-point numbers.
decimal and minor_units must identify the same value at the
currency's defined precision.
Show child attributes
Show child attributes
Merchant order or invoice reference.
Required string length:
1 - 128Example:
"merchant-order-20260730-001"
Merchant-defined string values returned unchanged.
Show child attributes
Show child attributes
Example:
{ "checkout_session": "checkout-001" }
Response
Payment created.
A successfully created payment with payer instructions. An unresolved
202 response uses the base Payment schema and may not have
instructions yet.
Pattern:
^pay_[A-Za-z0-9]{20,40}$Example:
"pay_01K1DRAFT8F7Z6K5Q4N3M2P1A0"
Current payment lifecycle state.
pending: Awaiting a definitive payment outcome.submission_unknown: Creation outcome requires retrieval; do not create a replacement payment.paid: The exact expected payment has been confirmed.denied: The payment was rejected.cancelled: The payment was cancelled before completion.review_required: The payment requires manual review.
Available options:
pending, submission_unknown, paid, denied, cancelled, review_required An exact monetary amount represented without floating-point numbers.
decimal and minor_units must identify the same value at the
currency's defined precision.
Show child attributes
Show child attributes
Instructions shown to the payer when available.
Show child attributes
Show child attributes
Sandbox / TRON Shasta preview environment.
Allowed value:
"sandbox"Example:
"sandbox"
Example:
"2026-07-30T15:10:00Z"
Example:
"2026-07-30T15:12:30Z"
Required string length:
1 - 128Example:
"merchant-order-20260730-001"
Merchant-defined string values returned unchanged.
Show child attributes
Show child attributes
Example:
{ "checkout_session": "checkout-001" }
⌘I