Create clearance

POST /v1/principal/clearance

Decides whether the caller's org may pay another org, BEFORE the payment: what must happen first, what must be withheld and why, what must be reported, by whom and when, and how the payment may settle net of withholding. Any member of the paying org; the decision is recorded and on the audit trail in one transaction.

The rules, each cited on the answer: payer's and payee's founders identity-verified (Hanzo policy); payer and payee screened clear of the OFAC, UN, EU and UK lists and the embargoed jurisdictions — a confirmed match blocks, a possible one waits on a Hanzo platform reviewer, and lists that are not loaded and fresh clear nobody; the payee's status is what the form the payee granted the payer says, and until it grants one the payee furnishes it; a U.S. payee with no TIN on file owes its W-9, and paid without one 24% backup withholding applies (IRC §3406); a foreign payee on a valid W-8BEN or W-8BEN-E is withheld on at 30% on U.S.-source income (IRC §1441, §1442), reduced by a treaty rate the form claims; a service performed outside the United States is foreign-source and not withheld on; Form 1099 by the payer for a reportable U.S. payee at the year's threshold, Forms 1042-S and 1042 for U.S.-source income to a foreign person, and platform-operator reports (EU DAC7, UK, Canada, Australia) where the payer is the payee's platform. Every filer named is an org, never Hanzo.

Nothing of the payee is answered but what the payer must know to act: that the payment clears, what the payee must furnish, or that it cannot clear and the payer should contact support — never why, and never the payee's status before the payee grants its form. A payer asks about at most 50 new payees a day and 120 payments an hour.

Request

6 fields, body application/json (required).

Response

201 body — 58 fields.

Failure carries the platform error shape — see Errors.

Examples

import { Configuration, PrincipalApi } from 'hanzoai';

const api = new PrincipalApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postPrincipalClearance({ amount: "<amount>", category: "<category>" });

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import PrincipalApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = PrincipalApi(client).post_principal_clearance(amount="<amount>", category="<category>")

cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.PrincipalAPI.PostPrincipalClearance(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_client::apis::{configuration::Configuration, principal_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = principal_api::post_principal_clearance(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.PrincipalApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new PrincipalApi(client).postPrincipalClearance();

curl -X POST https://api.hanzo.ai/v1/principal/clearance \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "amount": "<amount>",
       "category": "<category>"
     }'

Principal API · All Hanzo APIs · Interactive reference