Authorize a Vault funding operation

Authorize my Vault funding operation

curl --request POST \
  --url https://prod-api.stableyard.fi/v2/client/me/payments/{paymentId}/options/{optionId}/authorize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'X-Stableyard-Payment-Secret: <api-key>' \
  --data '
{
  "actionId": "fund_auth_123",
  "proof": {
    "type": "managed_authorization",
    "authorization": "approved"
  }
}
'

import requests

url = "https://prod-api.stableyard.fi/v2/client/me/payments/{paymentId}/options/{optionId}/authorize"

payload = {
    "actionId": "fund_auth_123",
    "proof": {
        "type": "managed_authorization",
        "authorization": "approved"
    }
}
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({
    actionId: 'fund_auth_123',
    proof: {type: 'managed_authorization', authorization: 'approved'}
  })
};

fetch('https://prod-api.stableyard.fi/v2/client/me/payments/{paymentId}/options/{optionId}/authorize', 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/{optionId}/authorize",
  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([
    'actionId' => 'fund_auth_123',
    'proof' => [
        'type' => 'managed_authorization',
        'authorization' => 'approved'
    ]
  ]),
  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/{optionId}/authorize"

	payload := strings.NewReader("{\n  \"actionId\": \"fund_auth_123\",\n  \"proof\": {\n    \"type\": \"managed_authorization\",\n    \"authorization\": \"approved\"\n  }\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/{optionId}/authorize")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("X-Stableyard-Payment-Secret", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"actionId\": \"fund_auth_123\",\n  \"proof\": {\n    \"type\": \"managed_authorization\",\n    \"authorization\": \"approved\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://prod-api.stableyard.fi/v2/client/me/payments/{paymentId}/options/{optionId}/authorize")

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  \"actionId\": \"fund_auth_123\",\n  \"proof\": {\n    \"type\": \"managed_authorization\",\n    \"authorization\": \"approved\"\n  }\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": null,
    "expiresAt": null,
    "refreshable": false,
    "feeAmountAtomic": "0",
    "actionExpiresAt": null,
    "quoteExpiresAt": null,
    "orderExpiresAt": null,
    "receipts": []
  },
  "fundingOperation": {
    "id": "pay_funding_123",
    "status": "authorized",
    "statusVersion": 2,
    "commercialFeeMode": "parent_payment",
    "transactionHash": null,
    "authorizedAt": "2026-09-01T12:01:00.000Z",
    "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"
  }
}

POST

client

payments

{paymentId}

options

{optionId}

authorize

Authorize my Vault funding operation

curl --request POST \
  --url https://prod-api.stableyard.fi/v2/client/me/payments/{paymentId}/options/{optionId}/authorize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'X-Stableyard-Payment-Secret: <api-key>' \
  --data '
{
  "actionId": "fund_auth_123",
  "proof": {
    "type": "managed_authorization",
    "authorization": "approved"
  }
}
'

import requests

url = "https://prod-api.stableyard.fi/v2/client/me/payments/{paymentId}/options/{optionId}/authorize"

payload = {
    "actionId": "fund_auth_123",
    "proof": {
        "type": "managed_authorization",
        "authorization": "approved"
    }
}
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({
    actionId: 'fund_auth_123',
    proof: {type: 'managed_authorization', authorization: 'approved'}
  })
};

fetch('https://prod-api.stableyard.fi/v2/client/me/payments/{paymentId}/options/{optionId}/authorize', 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/{optionId}/authorize",
  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([
    'actionId' => 'fund_auth_123',
    'proof' => [
        'type' => 'managed_authorization',
        'authorization' => 'approved'
    ]
  ]),
  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/{optionId}/authorize"

	payload := strings.NewReader("{\n  \"actionId\": \"fund_auth_123\",\n  \"proof\": {\n    \"type\": \"managed_authorization\",\n    \"authorization\": \"approved\"\n  }\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/{optionId}/authorize")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("X-Stableyard-Payment-Secret", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"actionId\": \"fund_auth_123\",\n  \"proof\": {\n    \"type\": \"managed_authorization\",\n    \"authorization\": \"approved\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://prod-api.stableyard.fi/v2/client/me/payments/{paymentId}/options/{optionId}/authorize")

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  \"actionId\": \"fund_auth_123\",\n  \"proof\": {\n    \"type\": \"managed_authorization\",\n    \"authorization\": \"approved\"\n  }\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": null,
    "expiresAt": null,
    "refreshable": false,
    "feeAmountAtomic": "0",
    "actionExpiresAt": null,
    "quoteExpiresAt": null,
    "orderExpiresAt": null,
    "receipts": []
  },
  "fundingOperation": {
    "id": "pay_funding_123",
    "status": "authorized",
    "statusVersion": 2,
    "commercialFeeMode": "parent_payment",
    "transactionHash": null,
    "authorizedAt": "2026-09-01T12:01:00.000Z",
    "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"
  }
}

Consumes the one-time actionId from the selected option’s execution object and authorizes Stableyard to execute the exact Vault-to-escrow transfer under the active policy. The client bearer token identifies the payer UPA; X-Stableyard-Payment-Secret binds the command to one Payment. A successful response means authorization was recorded, not that funds arrived or the Payment completed. Stableyard independently verifies the on-chain transfer to the escrow (chain, token, recipient, amount, success, finality and receipt uniqueness), and only verified escrow receipt evidence advances collection. Underpayments, duplicate receipts, late payments and execution failures follow the Payment’s normal reconciliation and recovery states. Idempotency-Key is required; reusing it with different input returns 409 idempotency_conflict.

Authorizations

Authorization

string

header

required

Short-lived account-bound token returned by POST /v2/client/auth/exchange.

X-Stableyard-Payment-Secret

string

header

required

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

Idempotency-Key

string

required

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 - 256

Pattern: ^[ -~]+$

Example:

"vault-payment-option-01"

Path Parameters

paymentId

string

required

Canonical receive Payment whose escrow will be funded.

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

Example:

"payment_123"

optionId

string

required

Vault option returned by the account-bound option endpoint.

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

Example:

"pay_option_vault_123"

Body

application/json

actionId

string

required

Single-use action identifier returned in option.execution.actionId.

Required string length: 1 - 128

Example:

"fund_auth_123"

proof

object

required

Show child attributes

metadata

object

Optional partner metadata. Must be JSON-safe, at most 4096 bytes, depth 3, 25 keys per object, 512 characters per string, and 50 items per array.

Response

Vault funding operation authorized for asynchronous execution

paymentId

string

required

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

Example:

"payment_123"

option

object

required

Show child attributes

fundingOperation

object

required

Show child attributes

Introduction

Onboarding

Accounts

Money movement

Activity

Vaults

Client & checkout

Platform

Authorize a Vault funding operation

Authorizations

Headers

Path Parameters

Body

Response