Submit a transaction for a checkout payment

Submit transaction candidate

curl --request POST \
  --url https://prod-api.stableyard.fi/v2/public/payments/{paymentId}/transactions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "optionId": "option_123",
  "transactionHash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
'

import requests

url = "https://prod-api.stableyard.fi/v2/public/payments/{paymentId}/transactions"

payload = {
    "optionId": "option_123",
    "transactionHash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    optionId: 'option_123',
    transactionHash: '0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'
  })
};

fetch('https://prod-api.stableyard.fi/v2/public/payments/{paymentId}/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://prod-api.stableyard.fi/v2/public/payments/{paymentId}/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([
    'optionId' => 'option_123',
    'transactionHash' => '0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://prod-api.stableyard.fi/v2/public/payments/{paymentId}/transactions"

	payload := strings.NewReader("{\n  \"optionId\": \"option_123\",\n  \"transactionHash\": \"0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://prod-api.stableyard.fi/v2/public/payments/{paymentId}/transactions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"optionId\": \"option_123\",\n  \"transactionHash\": \"0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://prod-api.stableyard.fi/v2/public/payments/{paymentId}/transactions")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"optionId\": \"option_123\",\n  \"transactionHash\": \"0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"\n}"

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

{
  "transactionHash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "purpose": "destination_escrow",
  "status": "submitted",
  "failureCode": null,
  "submittedAt": "2026-08-28T10:00:00.000Z",
  "verifiedAt": null
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Authentication is required"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "The credential does not allow this operation"
  }
}

{
  "error": {
    "code": "not_found",
    "message": "The resource was not found"
  }
}

{
  "error": {
    "code": "idempotency_conflict",
    "message": "The Idempotency-Key was already used with a different request"
  }
}

{
  "error": {
    "code": "payment_method_not_supported",
    "message": "The requested payment method is not supported"
  }
}

{
  "error": {
    "code": "chain_config_missing",
    "message": "The requested network is not configured for this environment"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests"
  }
}

POST

public

payments

{paymentId}

transactions

Submit transaction candidate

curl --request POST \
  --url https://prod-api.stableyard.fi/v2/public/payments/{paymentId}/transactions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "optionId": "option_123",
  "transactionHash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
'

import requests

url = "https://prod-api.stableyard.fi/v2/public/payments/{paymentId}/transactions"

payload = {
    "optionId": "option_123",
    "transactionHash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    optionId: 'option_123',
    transactionHash: '0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'
  })
};

fetch('https://prod-api.stableyard.fi/v2/public/payments/{paymentId}/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://prod-api.stableyard.fi/v2/public/payments/{paymentId}/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([
    'optionId' => 'option_123',
    'transactionHash' => '0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://prod-api.stableyard.fi/v2/public/payments/{paymentId}/transactions"

	payload := strings.NewReader("{\n  \"optionId\": \"option_123\",\n  \"transactionHash\": \"0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://prod-api.stableyard.fi/v2/public/payments/{paymentId}/transactions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"optionId\": \"option_123\",\n  \"transactionHash\": \"0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://prod-api.stableyard.fi/v2/public/payments/{paymentId}/transactions")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"optionId\": \"option_123\",\n  \"transactionHash\": \"0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"\n}"

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

{
  "transactionHash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "purpose": "destination_escrow",
  "status": "submitted",
  "failureCode": null,
  "submittedAt": "2026-08-28T10:00:00.000Z",
  "verifiedAt": null
}

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Authentication is required"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "The credential does not allow this operation"
  }
}

{
  "error": {
    "code": "not_found",
    "message": "The resource was not found"
  }
}

{
  "error": {
    "code": "idempotency_conflict",
    "message": "The Idempotency-Key was already used with a different request"
  }
}

{
  "error": {
    "code": "payment_method_not_supported",
    "message": "The requested payment method is not supported"
  }
}

{
  "error": {
    "code": "chain_config_missing",
    "message": "The requested network is not configured for this environment"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests"
  }
}

Submits an untrusted transactionHash for an optionId:

Routing methods always use this endpoint for the payer’s source transaction, across EVM, Solana, Movement, Tron and Bitcoin sources. Stableyard verifies the source transaction and the final settlement.
Direct Movement payments require hash submission.
Supported direct EVM escrow also accepts the hash. Detection stays automatic (confirmationMode: provider_webhook): submitting the hash only lets Stableyard catch a reverted transfer sooner, and does not credit the Payment.
Direct Solana payments are detected automatically and do not use this endpoint. Tron and Bitcoin cannot be direct Payment destinations.

A 202 response means the candidate was accepted for verification.

Authorizations

Authorization

string

header

required

Short-lived browser capability for exactly one payment_* resource. Never place it in a URL.

Path Parameters

paymentId

string

required

The payment_* ID returned when the Payment was created.

Pattern: ^payment_[A-Za-z0-9_-]+$

Example:

"payment_123"

Body

application/json

optionId

string

required

Required string length: 1 - 128

transactionHash

string

required

Required string length: 1 - 256

Response

Transaction accepted for verification

transactionHash

string

required

Canonical EVM/Movement transaction hash, Bitcoin/Tron transaction id, or Solana transaction signature.

Pattern: ^(0x[0-9a-fA-F]{64}|[0-9a-fA-F]{64}|[1-9A-HJ-NP-Za-km-z]{80,90})$

status

enum<string>

required

Available options:

submitted,

verifying,

verified,

rejected,

requires_intervention

failureCode

enum<string> | null

required

Available options:

invalid_payment_binding,

invalid_transaction_hash,

transaction_failed,

invalid_transaction_type,

transaction_hash_mismatch,

invalid_transfer_function,

invalid_transfer_arguments,

asset_mismatch,

destination_mismatch,

transaction_already_used,

transaction_not_confirmed,

transaction_verification_unavailable,

payment_option_missing,

routing_transaction_rejected,

null

submittedAt

string<date-time>

required

verifiedAt

string<date-time> | null

required

purpose

enum<string>

destination_escrow: a direct transfer to the Payment escrow. routing_source: the payer's source transaction for a Routing option. May be omitted on older submissions.

Available options:

destination_escrow,

routing_source

Introduction

Onboarding

Accounts

Money movement

Activity

Vaults

Client & checkout

Platform

Submit a transaction for a checkout payment

Authorizations

Path Parameters

Body

Response