API reference

Settings and compliance reference

Business-level invoice tolerance defaults and the lightweight compliance intake profile that can be managed through the dashboard UI or via API key.

GET/api/v1/businesses/:id/settings/invoicesx-api-keySandbox + live

Read invoice underpayment tolerance defaults

Return the business default invoice underpayment tolerance configuration.

When to use it

Use before creating invoices that inherit business defaults.

Field	Location	Required	Description	Example / default
id	path	Yes	Business ID.	-

Common errors

401: Missing or invalid API key.
404: Requested resource does not exist or is not owned by the business.

Sample response

json

{
  "businessId": "biz_123",
  "invoiceUnderpaymentToleranceBps": 50,
  "invoiceUnderpaymentToleranceMaxUsd": "0.50"
}

cURL example

bash

curl -X GET "https://api.paychainhq.io/api/v1/businesses/biz_123/settings/invoices" \
  -H "Content-Type: application/json" \
  -H "x-api-key: pk_live_your_business_key"

Node.js example

const response = await fetch('https://api.paychainhq.io/api/v1/businesses/biz_123/settings/invoices', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'pk_live_your_business_key',
  },
});
const payload = await response.json();
console.log(payload);

PATCH/api/v1/businesses/:id/settings/invoicesx-api-keySandbox + live

Update invoice underpayment tolerance defaults

Set default underpayment tolerance for newly created invoices.

When to use it

Use when your operation wants to accept small quote drift without blocking future invoices.

Idempotency: required

Field	Location	Required	Description	Example / default
id	path	Yes	Business ID.	-
invoiceUnderpaymentToleranceBps	body	No	Tolerance in basis points, max 300.	-
invoiceUnderpaymentToleranceMaxUsd	body	No	Absolute max shortfall in USD, max 100.00.	-

Cautions

The effective tolerance is the smaller of the bps-derived value and the USD cap.

Common errors

401: Missing or invalid API key.
400: Payload shape, query params, or business-state validation failed.

Sample request body

json

{
  "invoiceUnderpaymentToleranceBps": 50,
  "invoiceUnderpaymentToleranceMaxUsd": "0.50"
}

Sample response

json

{
  "businessId": "biz_123",
  "invoiceUnderpaymentToleranceBps": 50,
  "invoiceUnderpaymentToleranceMaxUsd": "0.50"
}

cURL example

bash

curl -X PATCH "https://api.paychainhq.io/api/v1/businesses/biz_123/settings/invoices" \
  -H "Content-Type: application/json" \
  -H "x-api-key: pk_live_your_business_key" \
  -H "Idempotency-Key: example-request-001" \
  -d '{
  "invoiceUnderpaymentToleranceBps": 50,
  "invoiceUnderpaymentToleranceMaxUsd": "0.50"
}'

Node.js example

const response = await fetch('https://api.paychainhq.io/api/v1/businesses/biz_123/settings/invoices', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'pk_live_your_business_key',
    'Idempotency-Key': 'example-request-001',
  },
  body: JSON.stringify({
  "invoiceUnderpaymentToleranceBps": 50,
  "invoiceUnderpaymentToleranceMaxUsd": "0.50"
}),
});
const payload = await response.json();
console.log(payload);

GET/api/v1/businesses/:id/compliance-profilex-api-keySandbox + live

Read compliance profile

Return the lightweight compliance intake profile and current review status.

When to use it

Use when rendering the compliance page or deciding whether live submission is ready.

Field	Location	Required	Description	Example / default
id	path	Yes	Business ID.	-

Common errors

401: Missing or invalid API key.
404: Requested resource does not exist or is not owned by the business.

Sample response

json

{
  "businessId": "biz_123",
  "orgId": "org_123",
  "profile": {
    "legalBusinessName": "Acme Treasury Ltd",
    "publicWebsite": "https://acme.io",
    "countryOfIncorporation": "NG",
    "primaryOperatingCountry": "NG",
    "contactFullName": "Ava Stone",
    "contactRole": "Operations Lead",
    "complianceEmail": "compliance@acme.io",
    "businessUseCase": "Onramp and payout settlement",
    "expectedMonthlyVolume": "$250k-$500k",
    "submittedAt": "2026-03-14T13:25:00.000Z",
    "intakeStatus": "submitted"
  },
  "reviewStatus": "profile_received",
  "complianceRequestedAt": "2026-03-14T12:00:00.000Z"
}

cURL example

bash

curl -X GET "https://api.paychainhq.io/api/v1/businesses/biz_123/compliance-profile" \
  -H "Content-Type: application/json" \
  -H "x-api-key: pk_live_your_business_key"

Node.js example

const response = await fetch('https://api.paychainhq.io/api/v1/businesses/biz_123/compliance-profile', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'pk_live_your_business_key',
  },
});
const payload = await response.json();
console.log(payload);

PATCH/api/v1/businesses/:id/compliance-profilex-api-keySandbox + live

Save compliance profile draft

Save partial compliance profile data without submitting for review.

When to use it

Use for draft-save behavior or to sync form edits from your operator console.

Idempotency: required

Field	Location	Required	Description	Example / default
id	path	Yes	Business ID.	-

Cautions

Submitting is a separate endpoint. Draft saves do not notify admins or start live review.

Common errors

401: Missing or invalid API key.
400: Payload shape, query params, or business-state validation failed.

Sample request body

json

{
  "legalBusinessName": "Acme Treasury Ltd",
  "publicWebsite": "https://acme.io",
  "countryOfIncorporation": "NG",
  "primaryOperatingCountry": "NG",
  "contactFullName": "Ava Stone",
  "contactRole": "Operations Lead",
  "complianceEmail": "compliance@acme.io",
  "businessUseCase": "Onramp and payout settlement",
  "expectedMonthlyVolume": "$250k-$500k"
}

Sample response

json

{
  "businessId": "biz_123",
  "orgId": "org_123",
  "profile": {
    "legalBusinessName": "Acme Treasury Ltd",
    "publicWebsite": "https://acme.io",
    "countryOfIncorporation": "NG",
    "primaryOperatingCountry": "NG",
    "contactFullName": "Ava Stone",
    "contactRole": "Operations Lead",
    "complianceEmail": "compliance@acme.io",
    "businessUseCase": "Onramp and payout settlement",
    "expectedMonthlyVolume": "$250k-$500k",
    "submittedAt": "2026-03-14T13:25:00.000Z",
    "intakeStatus": "submitted"
  },
  "reviewStatus": "profile_received",
  "complianceRequestedAt": "2026-03-14T12:00:00.000Z"
}

cURL example

bash

curl -X PATCH "https://api.paychainhq.io/api/v1/businesses/biz_123/compliance-profile" \
  -H "Content-Type: application/json" \
  -H "x-api-key: pk_live_your_business_key" \
  -H "Idempotency-Key: example-request-001" \
  -d '{
  "legalBusinessName": "Acme Treasury Ltd",
  "publicWebsite": "https://acme.io",
  "countryOfIncorporation": "NG",
  "primaryOperatingCountry": "NG",
  "contactFullName": "Ava Stone",
  "contactRole": "Operations Lead",
  "complianceEmail": "compliance@acme.io",
  "businessUseCase": "Onramp and payout settlement",
  "expectedMonthlyVolume": "$250k-$500k"
}'

Node.js example

const response = await fetch('https://api.paychainhq.io/api/v1/businesses/biz_123/compliance-profile', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'pk_live_your_business_key',
    'Idempotency-Key': 'example-request-001',
  },
  body: JSON.stringify({
  "legalBusinessName": "Acme Treasury Ltd",
  "publicWebsite": "https://acme.io",
  "countryOfIncorporation": "NG",
  "primaryOperatingCountry": "NG",
  "contactFullName": "Ava Stone",
  "contactRole": "Operations Lead",
  "complianceEmail": "compliance@acme.io",
  "businessUseCase": "Onramp and payout settlement",
  "expectedMonthlyVolume": "$250k-$500k"
}),
});
const payload = await response.json();
console.log(payload);

POST/api/v1/businesses/:id/compliance-profile/submitx-api-keySandbox + live

Submit compliance profile

Validate the compliance profile, mark it submitted, and notify admins.

When to use it

Call this when the lightweight intake is complete and ready for manual follow-up.

Idempotency: required

Field	Location	Required	Description	Example / default
id	path	Yes	Business ID.	-

Cautions

Submission requires every required field to be present and non-empty.

Common errors

401: Missing or invalid API key.
400: Payload shape, query params, or business-state validation failed.

Sample request body

json

{
  "legalBusinessName": "Acme Treasury Ltd",
  "publicWebsite": "https://acme.io",
  "countryOfIncorporation": "NG",
  "primaryOperatingCountry": "NG",
  "contactFullName": "Ava Stone",
  "contactRole": "Operations Lead",
  "complianceEmail": "compliance@acme.io",
  "businessUseCase": "Onramp and payout settlement",
  "expectedMonthlyVolume": "$250k-$500k"
}

Sample response

json

{
  "businessId": "biz_123",
  "orgId": "org_123",
  "profile": {
    "legalBusinessName": "Acme Treasury Ltd",
    "publicWebsite": "https://acme.io",
    "countryOfIncorporation": "NG",
    "primaryOperatingCountry": "NG",
    "contactFullName": "Ava Stone",
    "contactRole": "Operations Lead",
    "complianceEmail": "compliance@acme.io",
    "businessUseCase": "Onramp and payout settlement",
    "expectedMonthlyVolume": "$250k-$500k",
    "submittedAt": "2026-03-14T13:25:00.000Z",
    "intakeStatus": "submitted"
  },
  "reviewStatus": "profile_received",
  "complianceRequestedAt": "2026-03-14T12:00:00.000Z"
}

cURL example

bash

curl -X POST "https://api.paychainhq.io/api/v1/businesses/biz_123/compliance-profile/submit" \
  -H "Content-Type: application/json" \
  -H "x-api-key: pk_live_your_business_key" \
  -H "Idempotency-Key: example-request-001" \
  -d '{
  "legalBusinessName": "Acme Treasury Ltd",
  "publicWebsite": "https://acme.io",
  "countryOfIncorporation": "NG",
  "primaryOperatingCountry": "NG",
  "contactFullName": "Ava Stone",
  "contactRole": "Operations Lead",
  "complianceEmail": "compliance@acme.io",
  "businessUseCase": "Onramp and payout settlement",
  "expectedMonthlyVolume": "$250k-$500k"
}'

Node.js example

const response = await fetch('https://api.paychainhq.io/api/v1/businesses/biz_123/compliance-profile/submit', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'pk_live_your_business_key',
    'Idempotency-Key': 'example-request-001',
  },
  body: JSON.stringify({
  "legalBusinessName": "Acme Treasury Ltd",
  "publicWebsite": "https://acme.io",
  "countryOfIncorporation": "NG",
  "primaryOperatingCountry": "NG",
  "contactFullName": "Ava Stone",
  "contactRole": "Operations Lead",
  "complianceEmail": "compliance@acme.io",
  "businessUseCase": "Onramp and payout settlement",
  "expectedMonthlyVolume": "$250k-$500k"
}),
});
const payload = await response.json();
console.log(payload);

Business identity reference

Customers and invoices reference