Select my Vault Payment method
curl --request POST \
--url https://prod-api.stableyard.fi/v2/client/me/payments/{paymentId}/options \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--header 'X-Stableyard-Payment-Secret: <api-key>' \
--data '
{
"paymentMethodId": "vault.stableyard"
}
'import requests
url = "https://prod-api.stableyard.fi/v2/client/me/payments/{paymentId}/options"
payload = { "paymentMethodId": "vault.stableyard" }
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"X-Stableyard-Payment-Secret": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'X-Stableyard-Payment-Secret': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({paymentMethodId: 'vault.stableyard'})
};
fetch('https://prod-api.stableyard.fi/v2/client/me/payments/{paymentId}/options', 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/client/me/payments/{paymentId}/options",
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([
'paymentMethodId' => 'vault.stableyard'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>",
"X-Stableyard-Payment-Secret: <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"
"strings"
"net/http"
"io"
)
func main() {
url := "https://prod-api.stableyard.fi/v2/client/me/payments/{paymentId}/options"
payload := strings.NewReader("{\n \"paymentMethodId\": \"vault.stableyard\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("X-Stableyard-Payment-Secret", "<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://prod-api.stableyard.fi/v2/client/me/payments/{paymentId}/options")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("X-Stableyard-Payment-Secret", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"paymentMethodId\": \"vault.stableyard\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://prod-api.stableyard.fi/v2/client/me/payments/{paymentId}/options")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["X-Stableyard-Payment-Secret"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"paymentMethodId\": \"vault.stableyard\"\n}"
response = http.request(request)
puts response.read_body{
"paymentId": "payment_123",
"option": {
"id": "pay_option_vault_123",
"providerCode": "vault",
"paymentMethodType": "account_balance",
"paymentMethodId": "vault.stableyard",
"type": "account_balance",
"displayName": "Pay with Stableyard Vault",
"status": "pending",
"selectionStatus": "selected",
"requiredAmountAtomic": "10000000",
"paidAmountAtomic": "0",
"remainingAmountAtomic": "10000000",
"isTerminal": false,
"confirmationMode": "provider_webhook",
"transactionSubmissions": [],
"sourceAmount": {
"amountAtomic": "10000000",
"assetSymbol": "USDC",
"decimals": 6,
"chainId": 42161
},
"destinationAmount": {
"amountAtomic": "10000000",
"assetSymbol": "USDC",
"decimals": 6,
"chainId": 42161
},
"payerAmount": {
"amountAtomic": "10000000",
"amountDecimal": "10",
"assetSymbol": "USDC",
"decimals": 6,
"chainId": 42161,
"tokenAddress": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831"
},
"recipientAmount": {
"amountAtomic": "10000000",
"amountDecimal": "10",
"assetSymbol": "USDC",
"decimals": 6,
"chainId": 42161,
"tokenAddress": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831"
},
"providerFee": {
"amountAtomic": "0",
"amountDecimal": "0",
"assetSymbol": "USDC",
"decimals": 6,
"chainId": 42161,
"tokenAddress": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831"
},
"execution": {
"type": "managed_authorization",
"actionId": "fund_auth_123",
"authorization": "approved",
"expiresAt": "2026-09-01T12:10:00.000Z",
"confirmEndpoint": "/v2/client/me/payments/payment_123/options/pay_option_vault_123/authorize"
},
"expiresAt": null,
"refreshable": false,
"feeAmountAtomic": "0",
"actionExpiresAt": null,
"quoteExpiresAt": null,
"orderExpiresAt": null,
"receipts": []
},
"fundingOperation": {
"id": "pay_funding_123",
"status": "awaiting_authorization",
"statusVersion": 1,
"commercialFeeMode": "parent_payment",
"transactionHash": null,
"authorizedAt": null,
"broadcastAt": null,
"confirmedAt": null,
"expiresAt": "2026-09-01T12: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"
}
}{
"error": {
"code": "bad_request",
"message": "The request is invalid",
"details": "example"
}
}Client payments
Select the Vault payment method
Select the UPA’s Vault to fund a receive Payment’s escrow.
POST
/
v2
/
client
/
me
/
payments
/
{paymentId}
/
options
Select my Vault Payment method
curl --request POST \
--url https://prod-api.stableyard.fi/v2/client/me/payments/{paymentId}/options \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--header 'X-Stableyard-Payment-Secret: <api-key>' \
--data '
{
"paymentMethodId": "vault.stableyard"
}
'import requests
url = "https://prod-api.stableyard.fi/v2/client/me/payments/{paymentId}/options"
payload = { "paymentMethodId": "vault.stableyard" }
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"X-Stableyard-Payment-Secret": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'X-Stableyard-Payment-Secret': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({paymentMethodId: 'vault.stableyard'})
};
fetch('https://prod-api.stableyard.fi/v2/client/me/payments/{paymentId}/options', 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/client/me/payments/{paymentId}/options",
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([
'paymentMethodId' => 'vault.stableyard'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>",
"X-Stableyard-Payment-Secret: <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"
"strings"
"net/http"
"io"
)
func main() {
url := "https://prod-api.stableyard.fi/v2/client/me/payments/{paymentId}/options"
payload := strings.NewReader("{\n \"paymentMethodId\": \"vault.stableyard\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("X-Stableyard-Payment-Secret", "<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://prod-api.stableyard.fi/v2/client/me/payments/{paymentId}/options")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("X-Stableyard-Payment-Secret", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"paymentMethodId\": \"vault.stableyard\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://prod-api.stableyard.fi/v2/client/me/payments/{paymentId}/options")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["X-Stableyard-Payment-Secret"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"paymentMethodId\": \"vault.stableyard\"\n}"
response = http.request(request)
puts response.read_body{
"paymentId": "payment_123",
"option": {
"id": "pay_option_vault_123",
"providerCode": "vault",
"paymentMethodType": "account_balance",
"paymentMethodId": "vault.stableyard",
"type": "account_balance",
"displayName": "Pay with Stableyard Vault",
"status": "pending",
"selectionStatus": "selected",
"requiredAmountAtomic": "10000000",
"paidAmountAtomic": "0",
"remainingAmountAtomic": "10000000",
"isTerminal": false,
"confirmationMode": "provider_webhook",
"transactionSubmissions": [],
"sourceAmount": {
"amountAtomic": "10000000",
"assetSymbol": "USDC",
"decimals": 6,
"chainId": 42161
},
"destinationAmount": {
"amountAtomic": "10000000",
"assetSymbol": "USDC",
"decimals": 6,
"chainId": 42161
},
"payerAmount": {
"amountAtomic": "10000000",
"amountDecimal": "10",
"assetSymbol": "USDC",
"decimals": 6,
"chainId": 42161,
"tokenAddress": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831"
},
"recipientAmount": {
"amountAtomic": "10000000",
"amountDecimal": "10",
"assetSymbol": "USDC",
"decimals": 6,
"chainId": 42161,
"tokenAddress": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831"
},
"providerFee": {
"amountAtomic": "0",
"amountDecimal": "0",
"assetSymbol": "USDC",
"decimals": 6,
"chainId": 42161,
"tokenAddress": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831"
},
"execution": {
"type": "managed_authorization",
"actionId": "fund_auth_123",
"authorization": "approved",
"expiresAt": "2026-09-01T12:10:00.000Z",
"confirmEndpoint": "/v2/client/me/payments/payment_123/options/pay_option_vault_123/authorize"
},
"expiresAt": null,
"refreshable": false,
"feeAmountAtomic": "0",
"actionExpiresAt": null,
"quoteExpiresAt": null,
"orderExpiresAt": null,
"receipts": []
},
"fundingOperation": {
"id": "pay_funding_123",
"status": "awaiting_authorization",
"statusVersion": 1,
"commercialFeeMode": "parent_payment",
"transactionHash": null,
"authorizedAt": null,
"broadcastAt": null,
"confirmedAt": null,
"expiresAt": "2026-09-01T12: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"
}
}{
"error": {
"code": "bad_request",
"message": "The request is invalid",
"details": "example"
}
}Selects
vault.stableyard for this Payment. paymentMethodId is the only field you control: Stableyard derives the payer UPA, active Vault, payment source and active policy from the client token, and you cannot submit a vaultId, account locator, source or destination address, amount, policy or fee.
The resulting funding operation is private execution state under the existing Payment, and must fund the same immutable escrow amount as Direct crypto, Routing and hosted on-ramp methods. It has commercialFeeMode: parent_payment, so it never accrues a second platform or partner fee. Creating the option moves no money and does not complete the Payment; authorize it next.
Send the client bearer token and X-Stableyard-Payment-Secret. Idempotency-Key is required; reusing it with different input returns 409 idempotency_conflict.Authorizations
Short-lived account-bound token returned by POST /v2/client/auth/exchange.
Payment-specific secret used together with an account-bound Client bearer token. It proves access to exactly one Payment and must never be placed in a URL, analytics event, or log.
Headers
Required retry key for this account-bound Payment mutation. Reuse the same key only with the identical Payment, option, and body; different input returns 409 idempotency_conflict.
Required string length:
1 - 256Pattern:
^[ -~]+$Example:
"vault-payment-option-01"
Path Parameters
Canonical receive Payment whose escrow will be funded.
Pattern:
^payment_[A-Za-z0-9_-]+$Example:
"payment_123"
Body
application/json
The only caller-controlled field. Stableyard derives the UPA, Vault, source, active policy, escrow, amount, and fees.
Allowed value:
"vault.stableyard"