Get payment
curl --request GET \
--url https://prod-api.stableyard.fi/v2/payments/{paymentId} \
--header 'Authorization: Basic <encoded-value>'import requests
url = "https://prod-api.stableyard.fi/v2/payments/{paymentId}"
headers = {"Authorization": "Basic <encoded-value>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Basic <encoded-value>'}};
fetch('https://prod-api.stableyard.fi/v2/payments/{paymentId}', 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/payments/{paymentId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Basic <encoded-value>"
],
]);
$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://prod-api.stableyard.fi/v2/payments/{paymentId}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Basic <encoded-value>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://prod-api.stableyard.fi/v2/payments/{paymentId}")
.header("Authorization", "Basic <encoded-value>")
.asString();require 'uri'
require 'net/http'
url = URI("https://prod-api.stableyard.fi/v2/payments/{paymentId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Basic <encoded-value>'
response = http.request(request)
puts response.read_body{
"payment": {
"id": "payment_01JY8K4Q6P9A2M7T3W5X8Z1BCR",
"apiVersion": "2026-09-09",
"intent": "receive",
"amountMode": "collect_exact",
"status": "requires_payment_method",
"offrampStatus": null,
"stage": "awaiting_payment",
"operationalState": "normal",
"operationalReasonCode": null,
"operationalUpdatedAt": null,
"statusVersion": 1,
"paymentAmount": {
"amount": "25.00",
"amountAtomic": "25000000",
"assetType": "crypto",
"assetCode": "USDC",
"decimals": 6,
"chainId": 42161,
"tokenAddress": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831"
},
"participants": [
{
"role": "recipient",
"accountId": "acct_123"
}
],
"destination": {
"type": "upa",
"accountId": "acct_123"
},
"settlement": {
"type": "settlement_destination",
"settlementDestinationId": "destination_123",
"destinationType": "connected_wallet",
"destinationAddress": "0x1111111111111111111111111111111111111111",
"chainId": 42161,
"assetCode": "USDC",
"tokenAddress": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
"decimals": 6
},
"fees": {
"version": 1,
"pricingStatus": "quoted",
"platformFeeBps": 50,
"partnerFeeBps": 0,
"platformFeeAmountAtomic": "125000",
"partnerFeeAmountAtomic": "0",
"merchantNetAmountAtomic": "24875000"
},
"funding": null,
"externalReference": "order_1042",
"description": "Invoice #1042",
"metadata": {},
"expiresAt": "2026-08-28T10:10:00.000Z",
"acceptedAt": null,
"succeededAt": null,
"cancelledAt": null,
"failure": null,
"refundSummary": {
"status": "none",
"count": 0,
"requestedAmountAtomic": "0",
"confirmedAmountAtomic": "0"
},
"incidentRecoverySummary": {
"count": 0,
"pendingCount": 0,
"confirmedCount": 0,
"failedCount": 0,
"requiresInterventionCount": 0,
"requestedAmountAtomic": "0",
"confirmedAmountAtomic": "0"
},
"createdAt": "2026-08-28T10:00:00.000Z",
"updatedAt": "2026-08-28T10:00:00.000Z"
},
"nextAction": {
"id": "payment_01JY8K4Q6P9A2M7T3W5X8Z1BCR",
"type": "payment_method",
"expiresAt": "2026-08-28T10:10:00.000Z"
}
}{
"error": {
"code": "bad_request",
"message": "The request is invalid",
"details": "example"
}
}{
"error": {
"code": "bad_request",
"message": "The request is invalid",
"details": "example"
}
}{
"error": {
"code": "bad_request",
"message": "The request is invalid",
"details": "example"
}
}{
"error": {
"code": "bad_request",
"message": "The request is invalid",
"details": "example"
}
}{
"error": {
"code": "bad_request",
"message": "The request is invalid",
"details": "example"
}
}{
"error": {
"code": "bad_request",
"message": "The request is invalid",
"details": "example"
}
}{
"error": {
"code": "bad_request",
"message": "The request is invalid",
"details": "example"
}
}Payments
Get a payment
Fetch a Payment and the action it currently needs, if any.
GET
/
v2
/
payments
/
{paymentId}
Get payment
curl --request GET \
--url https://prod-api.stableyard.fi/v2/payments/{paymentId} \
--header 'Authorization: Basic <encoded-value>'import requests
url = "https://prod-api.stableyard.fi/v2/payments/{paymentId}"
headers = {"Authorization": "Basic <encoded-value>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Basic <encoded-value>'}};
fetch('https://prod-api.stableyard.fi/v2/payments/{paymentId}', 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/payments/{paymentId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Basic <encoded-value>"
],
]);
$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://prod-api.stableyard.fi/v2/payments/{paymentId}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Basic <encoded-value>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://prod-api.stableyard.fi/v2/payments/{paymentId}")
.header("Authorization", "Basic <encoded-value>")
.asString();require 'uri'
require 'net/http'
url = URI("https://prod-api.stableyard.fi/v2/payments/{paymentId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Basic <encoded-value>'
response = http.request(request)
puts response.read_body{
"payment": {
"id": "payment_01JY8K4Q6P9A2M7T3W5X8Z1BCR",
"apiVersion": "2026-09-09",
"intent": "receive",
"amountMode": "collect_exact",
"status": "requires_payment_method",
"offrampStatus": null,
"stage": "awaiting_payment",
"operationalState": "normal",
"operationalReasonCode": null,
"operationalUpdatedAt": null,
"statusVersion": 1,
"paymentAmount": {
"amount": "25.00",
"amountAtomic": "25000000",
"assetType": "crypto",
"assetCode": "USDC",
"decimals": 6,
"chainId": 42161,
"tokenAddress": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831"
},
"participants": [
{
"role": "recipient",
"accountId": "acct_123"
}
],
"destination": {
"type": "upa",
"accountId": "acct_123"
},
"settlement": {
"type": "settlement_destination",
"settlementDestinationId": "destination_123",
"destinationType": "connected_wallet",
"destinationAddress": "0x1111111111111111111111111111111111111111",
"chainId": 42161,
"assetCode": "USDC",
"tokenAddress": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
"decimals": 6
},
"fees": {
"version": 1,
"pricingStatus": "quoted",
"platformFeeBps": 50,
"partnerFeeBps": 0,
"platformFeeAmountAtomic": "125000",
"partnerFeeAmountAtomic": "0",
"merchantNetAmountAtomic": "24875000"
},
"funding": null,
"externalReference": "order_1042",
"description": "Invoice #1042",
"metadata": {},
"expiresAt": "2026-08-28T10:10:00.000Z",
"acceptedAt": null,
"succeededAt": null,
"cancelledAt": null,
"failure": null,
"refundSummary": {
"status": "none",
"count": 0,
"requestedAmountAtomic": "0",
"confirmedAmountAtomic": "0"
},
"incidentRecoverySummary": {
"count": 0,
"pendingCount": 0,
"confirmedCount": 0,
"failedCount": 0,
"requiresInterventionCount": 0,
"requestedAmountAtomic": "0",
"confirmedAmountAtomic": "0"
},
"createdAt": "2026-08-28T10:00:00.000Z",
"updatedAt": "2026-08-28T10:00:00.000Z"
},
"nextAction": {
"id": "payment_01JY8K4Q6P9A2M7T3W5X8Z1BCR",
"type": "payment_method",
"expiresAt": "2026-08-28T10:10:00.000Z"
}
}{
"error": {
"code": "bad_request",
"message": "The request is invalid",
"details": "example"
}
}{
"error": {
"code": "bad_request",
"message": "The request is invalid",
"details": "example"
}
}{
"error": {
"code": "bad_request",
"message": "The request is invalid",
"details": "example"
}
}{
"error": {
"code": "bad_request",
"message": "The request is invalid",
"details": "example"
}
}{
"error": {
"code": "bad_request",
"message": "The request is invalid",
"details": "example"
}
}{
"error": {
"code": "bad_request",
"message": "The request is invalid",
"details": "example"
}
}{
"error": {
"code": "bad_request",
"message": "The request is invalid",
"details": "example"
}
}Returns the canonical Payment and its current
nextAction, if one exists. Only the public payment_* identifier is accepted; execution and Payment Session identifiers are internal. The checkout client secret is issued when a receive Payment is created and is not returned by later reads.
See Status codes for the Payment lifecycle.Authorizations
HTTP Basic auth. Username is the Stableyard app ID. Password is the app secret. The optional Stableyard-Version request header must match the environment pin.
Headers
Optional contract-version assertion. Omit it to use the app environment's pinned version. A different supported version is accepted only after that environment is explicitly migrated.
Available options:
2026-09-09 Path Parameters
Canonical payment_* identifier. Internal execution identifiers are never accepted by Partner Payment routes.
Pattern:
^payment_[A-Za-z0-9_-]+$Example:
"payment_123"
Response
Payment details
Show child attributes
Show child attributes
The exact action the caller must complete. Null means Stableyard needs no action from the partner right now.
- Action required
- Start account KYC
- Verify UPA email
- Complete hosted compliance
- Wait for partner KYC
- Contact support
- No provider action
Show child attributes
Show child attributes
Show child attributes
Show child attributes