@peable.to/contracts 3.0.0 → 3.1.0

package/dist/cjs/resources/events/webhookDeliveries.js

@@ -26,7 +26,7 @@ exports.webhookDeliverySchema = (0, objects_1.defineObject)('webhook_delivery',
     delivered: zod_1.z.boolean(),
     last_status: zod_1.z
         .enum(events_1.WEBHOOK_DELIVERY_STATUSES)
-        .describe('`pending`: will be attempted (`next_attempt_at`). `delivered`: terminal success. `failed`: the endpoint refused it (a 4xx, a blocked address) or was disabled first — never retried. `dead`: every attempt failed transiently for three days; it can be redelivered.'),
+        .describe('`pending`: will be attempted (`next_attempt_at`). `delivered`: terminal success. `failed`: the endpoint refused it (a 4xx, a blocked address), was disabled first, or its stored url breaks the registration rules — never retried. `dead`: every attempt failed transiently for three days; it can be redelivered.'),
     last_error: zod_1.z
         .string()
         .optional()

package/dist/cjs/resources/events/webhookEndpoints.js

@@ -29,7 +29,7 @@ const endpointShape = {
     disabled_reason: zod_1.z
         .enum(events_1.WEBHOOK_ENDPOINT_DISABLED_REASONS)
         .nullable()
-        .describe('`null` exactly when `status` is `enabled`. `delivery_failures`: every delivery failed for three days straight.'),
+        .describe('`null` exactly when `status` is `enabled`. `delivery_failures`: every delivery failed for three days straight. `url_refused`: the stored `url` breaks the registration rules, judged before every delivery; re-enable it with a `url` that passes.'),
     api_version: zod_1.z.string().describe('The wire version events are rendered with for this endpoint.'),
     metadata: primitives_1.metadata,
     created: primitives_1.unixSeconds,

package/dist/cjs/resources/payments/disputes.js

@@ -7,6 +7,7 @@ const objects_1 = require("../../common/objects");
 const params_1 = require("../../common/params");
 const primitives_1 = require("../../common/primitives");
 const route_1 = require("../../route");
+const refunds_1 = require("./refunds");
 const payments_1 = require("../../vocabulary/payments");
 /**
  * Disputes (`dp_…`) — the card network holding a payment's money while a
@@ -201,4 +202,19 @@ exports.disputeRoutes = [
         response: exports.disputeSchema,
         sdk: 'disputes.close',
     }),
+    (0, route_1.defineRoute)({
+        operationId: 'retrieveDisputeSettlement',
+        method: 'get',
+        path: '/v1/disputes/{disputeId}/settlement',
+        tag: 'Disputes',
+        summary: "Retrieve a dispute's settlement",
+        description: 'What the dispute WITHDREW from the settlement balance — `gross` the principal, `fee` the dispute fee, a negative `net` — in the settlement currency, read live from the provider. An inquiry moves no money: `unknown`, every figure `null`, never `0`. A reinstatement after a won dispute is not this figure.',
+        auth: 'service',
+        scope: 'payments:read',
+        params: disputeId,
+        query: params_1.expandOnlyQuery,
+        response: refunds_1.settlementSchema,
+        sdk: 'disputes.settlement',
+        expandable: 'settlement',
+    }),
 ];

package/dist/cjs/resources/payments/refunds.js

@@ -10,7 +10,8 @@ const route_1 = require("../../route");
 const money_1 = require("../../vocabulary/money");
 const payments_1 = require("../../vocabulary/payments");
 /**
- * Refunds (`re_…`) and a payment's settlement figures. The provider's own
+ * Refunds (`re_…`) and the settlement figures of a payment, a refund or a
+ * dispute. The provider's own
  * refund id never appears: a merchant integrates against Peable and never
  * learns which acquirer sat behind it (ADR 0001 D3).
  */
@@ -56,23 +57,42 @@ exports.refundSchema = (0, objects_1.defineObject)('refund', 'Refund', zod_1.z
     ],
 });
 /**
- * What a payment actually came to, as the PROVIDER reports it. Every figure is
- * nullable and that is the contract: "the fee was zero" and "the fee is not
- * known yet" are different facts, and `status` says which produced the nulls.
- * It reports what the provider took; it attributes that cost to nobody.
+ * One movement of the settlement balance, as the PROVIDER reports it: what a
+ * payment brought in (`GET /v1/payment_intents/{intentId}/settlement`), what a
+ * refund took out (`GET /v1/refunds/{id}/settlement`) or what a dispute
+ * withdrew (`GET /v1/disputes/{disputeId}/settlement`). `refund` and `dispute`
+ * say which: both `null` for a payment's.
+ *
+ * Every figure is nullable and that is the contract: "the fee was zero" and
+ * "the fee is not known yet" are different facts, and `status` says which
+ * produced the nulls. It reports what the provider took; it attributes that
+ * cost to nobody.
+ *
+ * The signs: `gross` is the MAGNITUDE of the movement, `fee` the provider's fee
+ * on it (positive when charged, negative when returned), `net` its SIGNED
+ * effect on the balance — so `net = gross − fee` for a payment and
+ * `net = −gross − fee` for a refund or a dispute.
  */
 exports.settlementSchema = (0, objects_1.defineObject)('settlement', 'Settlement', zod_1.z
     .object({
     object: zod_1.z.literal('settlement'),
     livemode: primitives_1.livemode,
-    payment_intent: (0, objects_1.expandable)('payment_intent', 'The `pi_…` this describes, or the PaymentIntent with `expand[]=payment_intent`.'),
+    payment_intent: (0, objects_1.expandable)('payment_intent', 'The `pi_…` this describes (the refunded or disputed payment, for a refund or a dispute), or the PaymentIntent with `expand[]=payment_intent`.'),
+    refund: (0, objects_1.expandable)('refund', 'The `re_…` whose movement this is, or the Refund with `expand[]=refund`; `null` unless this is the settlement of a refund.').nullable(),
+    dispute: (0, objects_1.expandable)('dispute', 'The `dp_…` whose withdrawal this is, or the Dispute with `expand[]=dispute`; `null` unless this is the settlement of a dispute.').nullable(),
     status: zod_1.z
         .enum(payments_1.SETTLEMENT_STATUSES)
-        .describe('`available`: settled, the figures are final; `pending`: not final yet; `unknown`: there is none to read — **not zero**.'),
-    gross: primitives_1.amount.nullable().describe('Base units of `currency`.'),
-    fee: primitives_1.amount.nullable(),
-    net: primitives_1.signedAmount.nullable(),
-    currency: primitives_1.nullableString.describe("The SETTLEMENT currency (uppercase ISO 4217), which may differ from the payment's."),
+        .describe('`available`: settled, the figures are final; `pending`: not final yet; `unknown`: there is none to read — **not zero**. A dispute inquiry, which moves no money, and a refund that failed or was canceled are `unknown`.'),
+    gross: primitives_1.amount
+        .nullable()
+        .describe('The MAGNITUDE of the movement, never negative, in base units of `currency`: what the payment brought in, the refund took out or the dispute withdrew.'),
+    fee: primitives_1.signedAmount
+        .nullable()
+        .describe("The provider's fee on THIS movement, as the provider signs it: positive when charged to the balance (a payment's processing fee, a dispute fee), negative when returned to it (part of the original fee on some refunds). A refund's is usually `0`."),
+    net: primitives_1.signedAmount
+        .nullable()
+        .describe('The SIGNED effect on the balance: positive for a payment, negative for a refund or a dispute. Always `gross − fee` for a payment and `−gross − fee` for a refund or a dispute.'),
+    currency: primitives_1.nullableString.describe("The SETTLEMENT currency (uppercase ISO 4217) every figure is in, which may differ from the payment's, refund's or dispute's."),
     available_on: primitives_1.unixSeconds.nullable().describe('When the funds become available.'),
     exchange_rate: zod_1.z
         .number()
@@ -228,6 +248,21 @@ exports.refundRoutes = [
         sdk: 'refunds.settlement',
         expandable: 'settlement',
     }),
+    (0, route_1.defineRoute)({
+        operationId: 'retrieveRefundSettlement',
+        method: 'get',
+        path: '/v1/refunds/{id}/settlement',
+        tag: 'Refunds',
+        summary: "Retrieve a refund's settlement",
+        description: 'What the refund took off the settlement balance — `gross`, `fee`, a negative `net` — in the settlement currency, read live from the provider. A missing figure is `null` with a `status`, never `0`; a refund that failed or was canceled is `unknown`.',
+        auth: 'service',
+        scope: 'payments:read',
+        params: refundId,
+        query: params_1.expandOnlyQuery,
+        response: exports.settlementSchema,
+        sdk: 'refunds.refundSettlement',
+        expandable: 'settlement',
+    }),
     (0, route_1.defineRoute)({
         operationId: 'searchRefunds',
         method: 'get',

package/dist/cjs/vocabulary/events.js

@@ -150,10 +150,15 @@ exports.WEBHOOK_ENDPOINT_STATUSES = ['enabled', 'disabled'];
  *  - `delivery_failures`    — every delivery to it failed for three days
  *    straight, so Peable stopped sending. Re-enabling it (`disabled: false`)
  *    starts the clock again.
+ *  - `url_refused`          — its stored `url` breaks the rules a URL is
+ *    registered under (https in live mode, ports 80/443, no private, loopback
+ *    or reserved address), judged again before every delivery, so Peable never
+ *    sent to it. It is re-enabled only together with a `url` that passes.
  */
 exports.WEBHOOK_ENDPOINT_DISABLED_REASONS = [
     'disabled_by_merchant',
     'delivery_failures',
+    'url_refused',
 ];
 /** At most this many endpoints per merchant (per mode). */
 exports.WEBHOOK_ENDPOINTS_MAX_PER_MERCHANT = 16;

package/dist/esm/resources/events/webhookDeliveries.js

@@ -23,7 +23,7 @@ export const webhookDeliverySchema = defineObject('webhook_delivery', 'WebhookDe
     delivered: z.boolean(),
     last_status: z
         .enum(WEBHOOK_DELIVERY_STATUSES)
-        .describe('`pending`: will be attempted (`next_attempt_at`). `delivered`: terminal success. `failed`: the endpoint refused it (a 4xx, a blocked address) or was disabled first — never retried. `dead`: every attempt failed transiently for three days; it can be redelivered.'),
+        .describe('`pending`: will be attempted (`next_attempt_at`). `delivered`: terminal success. `failed`: the endpoint refused it (a 4xx, a blocked address), was disabled first, or its stored url breaks the registration rules — never retried. `dead`: every attempt failed transiently for three days; it can be redelivered.'),
     last_error: z
         .string()
         .optional()

package/dist/esm/resources/events/webhookEndpoints.js

@@ -26,7 +26,7 @@ const endpointShape = {
     disabled_reason: z
         .enum(WEBHOOK_ENDPOINT_DISABLED_REASONS)
         .nullable()
-        .describe('`null` exactly when `status` is `enabled`. `delivery_failures`: every delivery failed for three days straight.'),
+        .describe('`null` exactly when `status` is `enabled`. `delivery_failures`: every delivery failed for three days straight. `url_refused`: the stored `url` breaks the registration rules, judged before every delivery; re-enable it with a `url` that passes.'),
     api_version: z.string().describe('The wire version events are rendered with for this endpoint.'),
     metadata,
     created: unixSeconds,

package/dist/esm/resources/payments/disputes.js

@@ -4,6 +4,7 @@ import { defineComponent, defineObject, expandable } from '../../common/objects.
 import { expandOnlyQuery, idParam, listQuery, metadataUpdateParam } from '../../common/params.js';
 import { amount, currency, livemode, metadata, unixSeconds } from '../../common/primitives.js';
 import { defineRoute } from '../../route.js';
+import { settlementSchema } from './refunds.js';
 import { DISPUTE_EVIDENCE_TEXT_MAX, DISPUTE_FILE_EVIDENCE_FIELDS, DISPUTE_REASONS, DISPUTE_STATUSES, DISPUTE_TEXT_EVIDENCE_FIELDS, } from '../../vocabulary/payments.js';
 /**
  * Disputes (`dp_…`) — the card network holding a payment's money while a
@@ -198,4 +199,19 @@ export const disputeRoutes = [
         response: disputeSchema,
         sdk: 'disputes.close',
     }),
+    defineRoute({
+        operationId: 'retrieveDisputeSettlement',
+        method: 'get',
+        path: '/v1/disputes/{disputeId}/settlement',
+        tag: 'Disputes',
+        summary: "Retrieve a dispute's settlement",
+        description: 'What the dispute WITHDREW from the settlement balance — `gross` the principal, `fee` the dispute fee, a negative `net` — in the settlement currency, read live from the provider. An inquiry moves no money: `unknown`, every figure `null`, never `0`. A reinstatement after a won dispute is not this figure.',
+        auth: 'service',
+        scope: 'payments:read',
+        params: disputeId,
+        query: expandOnlyQuery,
+        response: settlementSchema,
+        sdk: 'disputes.settlement',
+        expandable: 'settlement',
+    }),
 ];

package/dist/esm/resources/payments/refunds.js

@@ -7,7 +7,8 @@ import { defineRoute } from '../../route.js';
 import { isBaseUnitString } from '../../vocabulary/money.js';
 import { REFUND_ORIGINS, REFUND_REASONS, REFUND_STATUSES, SETTLEMENT_STATUSES, } from '../../vocabulary/payments.js';
 /**
- * Refunds (`re_…`) and a payment's settlement figures. The provider's own
+ * Refunds (`re_…`) and the settlement figures of a payment, a refund or a
+ * dispute. The provider's own
  * refund id never appears: a merchant integrates against Peable and never
  * learns which acquirer sat behind it (ADR 0001 D3).
  */
@@ -53,23 +54,42 @@ export const refundSchema = defineObject('refund', 'Refund', z
     ],
 });
 /**
- * What a payment actually came to, as the PROVIDER reports it. Every figure is
- * nullable and that is the contract: "the fee was zero" and "the fee is not
- * known yet" are different facts, and `status` says which produced the nulls.
- * It reports what the provider took; it attributes that cost to nobody.
+ * One movement of the settlement balance, as the PROVIDER reports it: what a
+ * payment brought in (`GET /v1/payment_intents/{intentId}/settlement`), what a
+ * refund took out (`GET /v1/refunds/{id}/settlement`) or what a dispute
+ * withdrew (`GET /v1/disputes/{disputeId}/settlement`). `refund` and `dispute`
+ * say which: both `null` for a payment's.
+ *
+ * Every figure is nullable and that is the contract: "the fee was zero" and
+ * "the fee is not known yet" are different facts, and `status` says which
+ * produced the nulls. It reports what the provider took; it attributes that
+ * cost to nobody.
+ *
+ * The signs: `gross` is the MAGNITUDE of the movement, `fee` the provider's fee
+ * on it (positive when charged, negative when returned), `net` its SIGNED
+ * effect on the balance — so `net = gross − fee` for a payment and
+ * `net = −gross − fee` for a refund or a dispute.
  */
 export const settlementSchema = defineObject('settlement', 'Settlement', z
     .object({
     object: z.literal('settlement'),
     livemode,
-    payment_intent: expandable('payment_intent', 'The `pi_…` this describes, or the PaymentIntent with `expand[]=payment_intent`.'),
+    payment_intent: expandable('payment_intent', 'The `pi_…` this describes (the refunded or disputed payment, for a refund or a dispute), or the PaymentIntent with `expand[]=payment_intent`.'),
+    refund: expandable('refund', 'The `re_…` whose movement this is, or the Refund with `expand[]=refund`; `null` unless this is the settlement of a refund.').nullable(),
+    dispute: expandable('dispute', 'The `dp_…` whose withdrawal this is, or the Dispute with `expand[]=dispute`; `null` unless this is the settlement of a dispute.').nullable(),
     status: z
         .enum(SETTLEMENT_STATUSES)
-        .describe('`available`: settled, the figures are final; `pending`: not final yet; `unknown`: there is none to read — **not zero**.'),
-    gross: amount.nullable().describe('Base units of `currency`.'),
-    fee: amount.nullable(),
-    net: signedAmount.nullable(),
-    currency: nullableString.describe("The SETTLEMENT currency (uppercase ISO 4217), which may differ from the payment's."),
+        .describe('`available`: settled, the figures are final; `pending`: not final yet; `unknown`: there is none to read — **not zero**. A dispute inquiry, which moves no money, and a refund that failed or was canceled are `unknown`.'),
+    gross: amount
+        .nullable()
+        .describe('The MAGNITUDE of the movement, never negative, in base units of `currency`: what the payment brought in, the refund took out or the dispute withdrew.'),
+    fee: signedAmount
+        .nullable()
+        .describe("The provider's fee on THIS movement, as the provider signs it: positive when charged to the balance (a payment's processing fee, a dispute fee), negative when returned to it (part of the original fee on some refunds). A refund's is usually `0`."),
+    net: signedAmount
+        .nullable()
+        .describe('The SIGNED effect on the balance: positive for a payment, negative for a refund or a dispute. Always `gross − fee` for a payment and `−gross − fee` for a refund or a dispute.'),
+    currency: nullableString.describe("The SETTLEMENT currency (uppercase ISO 4217) every figure is in, which may differ from the payment's, refund's or dispute's."),
     available_on: unixSeconds.nullable().describe('When the funds become available.'),
     exchange_rate: z
         .number()
@@ -225,6 +245,21 @@ export const refundRoutes = [
         sdk: 'refunds.settlement',
         expandable: 'settlement',
     }),
+    defineRoute({
+        operationId: 'retrieveRefundSettlement',
+        method: 'get',
+        path: '/v1/refunds/{id}/settlement',
+        tag: 'Refunds',
+        summary: "Retrieve a refund's settlement",
+        description: 'What the refund took off the settlement balance — `gross`, `fee`, a negative `net` — in the settlement currency, read live from the provider. A missing figure is `null` with a `status`, never `0`; a refund that failed or was canceled is `unknown`.',
+        auth: 'service',
+        scope: 'payments:read',
+        params: refundId,
+        query: expandOnlyQuery,
+        response: settlementSchema,
+        sdk: 'refunds.refundSettlement',
+        expandable: 'settlement',
+    }),
     defineRoute({
         operationId: 'searchRefunds',
         method: 'get',

package/dist/esm/vocabulary/events.js

@@ -147,10 +147,15 @@ export const WEBHOOK_ENDPOINT_STATUSES = ['enabled', 'disabled'];
  *  - `delivery_failures`    — every delivery to it failed for three days
  *    straight, so Peable stopped sending. Re-enabling it (`disabled: false`)
  *    starts the clock again.
+ *  - `url_refused`          — its stored `url` breaks the rules a URL is
+ *    registered under (https in live mode, ports 80/443, no private, loopback
+ *    or reserved address), judged again before every delivery, so Peable never
+ *    sent to it. It is re-enabled only together with a `url` that passes.
  */
 export const WEBHOOK_ENDPOINT_DISABLED_REASONS = [
     'disabled_by_merchant',
     'delivery_failures',
+    'url_refused',
 ];
 /** At most this many endpoints per merchant (per mode). */
 export const WEBHOOK_ENDPOINTS_MAX_PER_MERCHANT = 16;

package/dist/types/resources/connect/balance.d.ts

@@ -54,8 +54,8 @@ export declare const balanceTransactionSchema: z.ZodObject<{
         payout: "payout";
         transfer: "transfer";
         charge: "charge";
-        dispute: "dispute";
         refund: "refund";
+        dispute: "dispute";
         adjustment: "adjustment";
         other: "other";
         payment: "payment";
@@ -147,8 +147,8 @@ export declare const listBalanceTransactionsQuery: z.ZodObject<{
         payout: "payout";
         transfer: "transfer";
         charge: "charge";
-        dispute: "dispute";
         refund: "refund";
+        dispute: "dispute";
         adjustment: "adjustment";
         other: "other";
         payment: "payment";
@@ -250,8 +250,8 @@ export declare const balanceRoutes: readonly [{
             payout: "payout";
             transfer: "transfer";
             charge: "charge";
-            dispute: "dispute";
             refund: "refund";
+            dispute: "dispute";
             adjustment: "adjustment";
             other: "other";
             payment: "payment";
@@ -284,8 +284,8 @@ export declare const balanceRoutes: readonly [{
                 payout: "payout";
                 transfer: "transfer";
                 charge: "charge";
-                dispute: "dispute";
                 refund: "refund";
+                dispute: "dispute";
                 adjustment: "adjustment";
                 other: "other";
                 payment: "payment";
@@ -356,8 +356,8 @@ export declare const balanceRoutes: readonly [{
             payout: "payout";
             transfer: "transfer";
             charge: "charge";
-            dispute: "dispute";
             refund: "refund";
+            dispute: "dispute";
             adjustment: "adjustment";
             other: "other";
             payment: "payment";

package/dist/types/resources/connect/index.d.ts

@@ -688,8 +688,8 @@ export declare const connectRoutes: readonly [{
             payout: "payout";
             transfer: "transfer";
             charge: "charge";
-            dispute: "dispute";
             refund: "refund";
+            dispute: "dispute";
             adjustment: "adjustment";
             other: "other";
             payment: "payment";
@@ -722,8 +722,8 @@ export declare const connectRoutes: readonly [{
                 payout: "payout";
                 transfer: "transfer";
                 charge: "charge";
-                dispute: "dispute";
                 refund: "refund";
+                dispute: "dispute";
                 adjustment: "adjustment";
                 other: "other";
                 payment: "payment";
@@ -794,8 +794,8 @@ export declare const connectRoutes: readonly [{
             payout: "payout";
             transfer: "transfer";
             charge: "charge";
-            dispute: "dispute";
             refund: "refund";
+            dispute: "dispute";
             adjustment: "adjustment";
             other: "other";
             payment: "payment";
@@ -1111,8 +1111,8 @@ export declare const connectRoutes: readonly [{
                 payout: "payout";
                 transfer: "transfer";
                 charge: "charge";
-                dispute: "dispute";
                 refund: "refund";
+                dispute: "dispute";
                 adjustment: "adjustment";
                 other: "other";
                 payment: "payment";

package/dist/types/resources/connect/payouts.d.ts

@@ -58,8 +58,8 @@ export declare const payoutReconciliationReportSchema: z.ZodObject<{
             payout: "payout";
             transfer: "transfer";
             charge: "charge";
-            dispute: "dispute";
             refund: "refund";
+            dispute: "dispute";
             adjustment: "adjustment";
             other: "other";
             payment: "payment";
@@ -468,8 +468,8 @@ export declare const payoutRoutes: readonly [{
                 payout: "payout";
                 transfer: "transfer";
                 charge: "charge";
-                dispute: "dispute";
                 refund: "refund";
+                dispute: "dispute";
                 adjustment: "adjustment";
                 other: "other";
                 payment: "payment";

package/dist/types/resources/events/index.d.ts

@@ -639,6 +639,7 @@ export declare const eventsRoutes: readonly [{
         disabled_reason: import("zod").ZodNullable<import("zod").ZodEnum<{
             disabled_by_merchant: "disabled_by_merchant";
             delivery_failures: "delivery_failures";
+            url_refused: "url_refused";
         }>>;
         api_version: import("zod").ZodString;
         metadata: import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodString>;
@@ -782,6 +783,7 @@ export declare const eventsRoutes: readonly [{
             disabled_reason: import("zod").ZodNullable<import("zod").ZodEnum<{
                 disabled_by_merchant: "disabled_by_merchant";
                 delivery_failures: "delivery_failures";
+                url_refused: "url_refused";
             }>>;
             api_version: import("zod").ZodString;
             metadata: import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodString>;
@@ -916,6 +918,7 @@ export declare const eventsRoutes: readonly [{
         disabled_reason: import("zod").ZodNullable<import("zod").ZodEnum<{
             disabled_by_merchant: "disabled_by_merchant";
             delivery_failures: "delivery_failures";
+            url_refused: "url_refused";
         }>>;
         api_version: import("zod").ZodString;
         metadata: import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodString>;
@@ -1146,6 +1149,7 @@ export declare const eventsRoutes: readonly [{
         disabled_reason: import("zod").ZodNullable<import("zod").ZodEnum<{
             disabled_by_merchant: "disabled_by_merchant";
             delivery_failures: "delivery_failures";
+            url_refused: "url_refused";
         }>>;
         api_version: import("zod").ZodString;
         metadata: import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodString>;
@@ -1296,6 +1300,7 @@ export declare const eventsRoutes: readonly [{
         disabled_reason: import("zod").ZodNullable<import("zod").ZodEnum<{
             disabled_by_merchant: "disabled_by_merchant";
             delivery_failures: "delivery_failures";
+            url_refused: "url_refused";
         }>>;
         api_version: import("zod").ZodString;
         metadata: import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodString>;

package/dist/types/resources/events/webhookEndpoints.d.ts

@@ -110,6 +110,7 @@ export declare const webhookEndpointSchema: z.ZodObject<{
     disabled_reason: z.ZodNullable<z.ZodEnum<{
         disabled_by_merchant: "disabled_by_merchant";
         delivery_failures: "delivery_failures";
+        url_refused: "url_refused";
     }>>;
     api_version: z.ZodString;
     metadata: z.ZodRecord<z.ZodString, z.ZodString>;
@@ -231,6 +232,7 @@ export declare const webhookEndpointWithSecretSchema: z.ZodObject<{
     disabled_reason: z.ZodNullable<z.ZodEnum<{
         disabled_by_merchant: "disabled_by_merchant";
         delivery_failures: "delivery_failures";
+        url_refused: "url_refused";
     }>>;
     api_version: z.ZodString;
     metadata: z.ZodRecord<z.ZodString, z.ZodString>;
@@ -694,6 +696,7 @@ export declare const webhookEndpointRoutes: readonly [{
         disabled_reason: z.ZodNullable<z.ZodEnum<{
             disabled_by_merchant: "disabled_by_merchant";
             delivery_failures: "delivery_failures";
+            url_refused: "url_refused";
         }>>;
         api_version: z.ZodString;
         metadata: z.ZodRecord<z.ZodString, z.ZodString>;
@@ -837,6 +840,7 @@ export declare const webhookEndpointRoutes: readonly [{
             disabled_reason: z.ZodNullable<z.ZodEnum<{
                 disabled_by_merchant: "disabled_by_merchant";
                 delivery_failures: "delivery_failures";
+                url_refused: "url_refused";
             }>>;
             api_version: z.ZodString;
             metadata: z.ZodRecord<z.ZodString, z.ZodString>;
@@ -971,6 +975,7 @@ export declare const webhookEndpointRoutes: readonly [{
         disabled_reason: z.ZodNullable<z.ZodEnum<{
             disabled_by_merchant: "disabled_by_merchant";
             delivery_failures: "delivery_failures";
+            url_refused: "url_refused";
         }>>;
         api_version: z.ZodString;
         metadata: z.ZodRecord<z.ZodString, z.ZodString>;
@@ -1201,6 +1206,7 @@ export declare const webhookEndpointRoutes: readonly [{
         disabled_reason: z.ZodNullable<z.ZodEnum<{
             disabled_by_merchant: "disabled_by_merchant";
             delivery_failures: "delivery_failures";
+            url_refused: "url_refused";
         }>>;
         api_version: z.ZodString;
         metadata: z.ZodRecord<z.ZodString, z.ZodString>;
@@ -1351,6 +1357,7 @@ export declare const webhookEndpointRoutes: readonly [{
         disabled_reason: z.ZodNullable<z.ZodEnum<{
             disabled_by_merchant: "disabled_by_merchant";
             delivery_failures: "delivery_failures";
+            url_refused: "url_refused";
         }>>;
         api_version: z.ZodString;
         metadata: z.ZodRecord<z.ZodString, z.ZodString>;

package/dist/types/resources/payments/disputes.d.ts

@@ -819,4 +819,39 @@ export declare const disputeRoutes: readonly [{
         updated_at: z.ZodNumber;
     }, z.core.$strict>;
     readonly sdk: "disputes.close";
+}, {
+    readonly operationId: "retrieveDisputeSettlement";
+    readonly method: "get";
+    readonly path: "/v1/disputes/{disputeId}/settlement";
+    readonly tag: "Disputes";
+    readonly summary: "Retrieve a dispute's settlement";
+    readonly description: "What the dispute WITHDREW from the settlement balance — `gross` the principal, `fee` the dispute fee, a negative `net` — in the settlement currency, read live from the provider. An inquiry moves no money: `unknown`, every figure `null`, never `0`. A reinstatement after a won dispute is not this figure.";
+    readonly auth: "service";
+    readonly scope: "payments:read";
+    readonly params: {
+        disputeId: string;
+    };
+    readonly query: z.ZodObject<{
+        expand: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<string[], string | string[]>>, z.ZodArray<z.ZodString>>>;
+    }, z.core.$strict>;
+    readonly response: z.ZodObject<{
+        object: z.ZodLiteral<"settlement">;
+        livemode: z.ZodBoolean;
+        payment_intent: z.ZodType<string | import("../..").Ref<"payment_intent">, string | import("../..").Ref<"payment_intent">, z.core.$ZodTypeInternals<string | import("../..").Ref<"payment_intent">, string | import("../..").Ref<"payment_intent">>>;
+        refund: z.ZodNullable<z.ZodType<string | import("../..").Ref<"refund">, string | import("../..").Ref<"refund">, z.core.$ZodTypeInternals<string | import("../..").Ref<"refund">, string | import("../..").Ref<"refund">>>>;
+        dispute: z.ZodNullable<z.ZodType<string | import("../..").Ref<"dispute">, string | import("../..").Ref<"dispute">, z.core.$ZodTypeInternals<string | import("../..").Ref<"dispute">, string | import("../..").Ref<"dispute">>>>;
+        status: z.ZodEnum<{
+            unknown: "unknown";
+            pending: "pending";
+            available: "available";
+        }>;
+        gross: z.ZodNullable<z.ZodString>;
+        fee: z.ZodNullable<z.ZodString>;
+        net: z.ZodNullable<z.ZodString>;
+        currency: z.ZodNullable<z.ZodString>;
+        available_on: z.ZodNullable<z.ZodNumber>;
+        exchange_rate: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strict>;
+    readonly sdk: "disputes.settlement";
+    readonly expandable: "settlement";
 }];

package/dist/types/resources/payments/index.d.ts

@@ -2306,6 +2306,8 @@ export declare const paymentsRoutes: readonly [{
         object: import("zod").ZodLiteral<"settlement">;
         livemode: import("zod").ZodBoolean;
         payment_intent: import("zod").ZodType<string | import("../..").Ref<"payment_intent">, string | import("../..").Ref<"payment_intent">, import("zod/v4/core").$ZodTypeInternals<string | import("../..").Ref<"payment_intent">, string | import("../..").Ref<"payment_intent">>>;
+        refund: import("zod").ZodNullable<import("zod").ZodType<string | import("../..").Ref<"refund">, string | import("../..").Ref<"refund">, import("zod/v4/core").$ZodTypeInternals<string | import("../..").Ref<"refund">, string | import("../..").Ref<"refund">>>>;
+        dispute: import("zod").ZodNullable<import("zod").ZodType<string | import("../..").Ref<"dispute">, string | import("../..").Ref<"dispute">, import("zod/v4/core").$ZodTypeInternals<string | import("../..").Ref<"dispute">, string | import("../..").Ref<"dispute">>>>;
         status: import("zod").ZodEnum<{
             unknown: "unknown";
             pending: "pending";
@@ -2320,6 +2322,41 @@ export declare const paymentsRoutes: readonly [{
     }, import("zod/v4/core").$strict>;
     readonly sdk: "refunds.settlement";
     readonly expandable: "settlement";
+}, {
+    readonly operationId: "retrieveRefundSettlement";
+    readonly method: "get";
+    readonly path: "/v1/refunds/{id}/settlement";
+    readonly tag: "Refunds";
+    readonly summary: "Retrieve a refund's settlement";
+    readonly description: "What the refund took off the settlement balance — `gross`, `fee`, a negative `net` — in the settlement currency, read live from the provider. A missing figure is `null` with a `status`, never `0`; a refund that failed or was canceled is `unknown`.";
+    readonly auth: "service";
+    readonly scope: "payments:read";
+    readonly params: {
+        id: string;
+    };
+    readonly query: import("zod").ZodObject<{
+        expand: import("zod").ZodOptional<import("zod").ZodPipe<import("zod").ZodPipe<import("zod").ZodUnion<readonly [import("zod").ZodString, import("zod").ZodArray<import("zod").ZodString>]>, import("zod").ZodTransform<string[], string | string[]>>, import("zod").ZodArray<import("zod").ZodString>>>;
+    }, import("zod/v4/core").$strict>;
+    readonly response: import("zod").ZodObject<{
+        object: import("zod").ZodLiteral<"settlement">;
+        livemode: import("zod").ZodBoolean;
+        payment_intent: import("zod").ZodType<string | import("../..").Ref<"payment_intent">, string | import("../..").Ref<"payment_intent">, import("zod/v4/core").$ZodTypeInternals<string | import("../..").Ref<"payment_intent">, string | import("../..").Ref<"payment_intent">>>;
+        refund: import("zod").ZodNullable<import("zod").ZodType<string | import("../..").Ref<"refund">, string | import("../..").Ref<"refund">, import("zod/v4/core").$ZodTypeInternals<string | import("../..").Ref<"refund">, string | import("../..").Ref<"refund">>>>;
+        dispute: import("zod").ZodNullable<import("zod").ZodType<string | import("../..").Ref<"dispute">, string | import("../..").Ref<"dispute">, import("zod/v4/core").$ZodTypeInternals<string | import("../..").Ref<"dispute">, string | import("../..").Ref<"dispute">>>>;
+        status: import("zod").ZodEnum<{
+            unknown: "unknown";
+            pending: "pending";
+            available: "available";
+        }>;
+        gross: import("zod").ZodNullable<import("zod").ZodString>;
+        fee: import("zod").ZodNullable<import("zod").ZodString>;
+        net: import("zod").ZodNullable<import("zod").ZodString>;
+        currency: import("zod").ZodNullable<import("zod").ZodString>;
+        available_on: import("zod").ZodNullable<import("zod").ZodNumber>;
+        exchange_rate: import("zod").ZodNullable<import("zod").ZodNumber>;
+    }, import("zod/v4/core").$strict>;
+    readonly sdk: "refunds.refundSettlement";
+    readonly expandable: "settlement";
 }, {
     readonly operationId: "searchRefunds";
     readonly method: "get";
@@ -2958,6 +2995,41 @@ export declare const paymentsRoutes: readonly [{
         updated_at: import("zod").ZodNumber;
     }, import("zod/v4/core").$strict>;
     readonly sdk: "disputes.close";
+}, {
+    readonly operationId: "retrieveDisputeSettlement";
+    readonly method: "get";
+    readonly path: "/v1/disputes/{disputeId}/settlement";
+    readonly tag: "Disputes";
+    readonly summary: "Retrieve a dispute's settlement";
+    readonly description: "What the dispute WITHDREW from the settlement balance — `gross` the principal, `fee` the dispute fee, a negative `net` — in the settlement currency, read live from the provider. An inquiry moves no money: `unknown`, every figure `null`, never `0`. A reinstatement after a won dispute is not this figure.";
+    readonly auth: "service";
+    readonly scope: "payments:read";
+    readonly params: {
+        disputeId: string;
+    };
+    readonly query: import("zod").ZodObject<{
+        expand: import("zod").ZodOptional<import("zod").ZodPipe<import("zod").ZodPipe<import("zod").ZodUnion<readonly [import("zod").ZodString, import("zod").ZodArray<import("zod").ZodString>]>, import("zod").ZodTransform<string[], string | string[]>>, import("zod").ZodArray<import("zod").ZodString>>>;
+    }, import("zod/v4/core").$strict>;
+    readonly response: import("zod").ZodObject<{
+        object: import("zod").ZodLiteral<"settlement">;
+        livemode: import("zod").ZodBoolean;
+        payment_intent: import("zod").ZodType<string | import("../..").Ref<"payment_intent">, string | import("../..").Ref<"payment_intent">, import("zod/v4/core").$ZodTypeInternals<string | import("../..").Ref<"payment_intent">, string | import("../..").Ref<"payment_intent">>>;
+        refund: import("zod").ZodNullable<import("zod").ZodType<string | import("../..").Ref<"refund">, string | import("../..").Ref<"refund">, import("zod/v4/core").$ZodTypeInternals<string | import("../..").Ref<"refund">, string | import("../..").Ref<"refund">>>>;
+        dispute: import("zod").ZodNullable<import("zod").ZodType<string | import("../..").Ref<"dispute">, string | import("../..").Ref<"dispute">, import("zod/v4/core").$ZodTypeInternals<string | import("../..").Ref<"dispute">, string | import("../..").Ref<"dispute">>>>;
+        status: import("zod").ZodEnum<{
+            unknown: "unknown";
+            pending: "pending";
+            available: "available";
+        }>;
+        gross: import("zod").ZodNullable<import("zod").ZodString>;
+        fee: import("zod").ZodNullable<import("zod").ZodString>;
+        net: import("zod").ZodNullable<import("zod").ZodString>;
+        currency: import("zod").ZodNullable<import("zod").ZodString>;
+        available_on: import("zod").ZodNullable<import("zod").ZodNumber>;
+        exchange_rate: import("zod").ZodNullable<import("zod").ZodNumber>;
+    }, import("zod/v4/core").$strict>;
+    readonly sdk: "disputes.settlement";
+    readonly expandable: "settlement";
 }, {
     readonly operationId: "createSetupIntent";
     readonly method: "post";

package/dist/types/resources/payments/refunds.d.ts

@@ -1,7 +1,8 @@
 import { z } from 'zod';
 import { type Expand } from '../../common/objects';
 /**
- * Refunds (`re_…`) and a payment's settlement figures. The provider's own
+ * Refunds (`re_…`) and the settlement figures of a payment, a refund or a
+ * dispute. The provider's own
  * refund id never appears: a merchant integrates against Peable and never
  * learns which acquirer sat behind it (ADR 0001 D3).
  */
@@ -49,15 +50,28 @@ export declare const refundSchema: z.ZodObject<{
 }, z.core.$strict>;
 export type Refund = Expand<z.output<typeof refundSchema>>;
 /**
- * What a payment actually came to, as the PROVIDER reports it. Every figure is
- * nullable and that is the contract: "the fee was zero" and "the fee is not
- * known yet" are different facts, and `status` says which produced the nulls.
- * It reports what the provider took; it attributes that cost to nobody.
+ * One movement of the settlement balance, as the PROVIDER reports it: what a
+ * payment brought in (`GET /v1/payment_intents/{intentId}/settlement`), what a
+ * refund took out (`GET /v1/refunds/{id}/settlement`) or what a dispute
+ * withdrew (`GET /v1/disputes/{disputeId}/settlement`). `refund` and `dispute`
+ * say which: both `null` for a payment's.
+ *
+ * Every figure is nullable and that is the contract: "the fee was zero" and
+ * "the fee is not known yet" are different facts, and `status` says which
+ * produced the nulls. It reports what the provider took; it attributes that
+ * cost to nobody.
+ *
+ * The signs: `gross` is the MAGNITUDE of the movement, `fee` the provider's fee
+ * on it (positive when charged, negative when returned), `net` its SIGNED
+ * effect on the balance — so `net = gross − fee` for a payment and
+ * `net = −gross − fee` for a refund or a dispute.
  */
 export declare const settlementSchema: z.ZodObject<{
     object: z.ZodLiteral<"settlement">;
     livemode: z.ZodBoolean;
     payment_intent: z.ZodType<string | import("../..").Ref<"payment_intent">, string | import("../..").Ref<"payment_intent">, z.core.$ZodTypeInternals<string | import("../..").Ref<"payment_intent">, string | import("../..").Ref<"payment_intent">>>;
+    refund: z.ZodNullable<z.ZodType<string | import("../..").Ref<"refund">, string | import("../..").Ref<"refund">, z.core.$ZodTypeInternals<string | import("../..").Ref<"refund">, string | import("../..").Ref<"refund">>>>;
+    dispute: z.ZodNullable<z.ZodType<string | import("../..").Ref<"dispute">, string | import("../..").Ref<"dispute">, z.core.$ZodTypeInternals<string | import("../..").Ref<"dispute">, string | import("../..").Ref<"dispute">>>>;
     status: z.ZodEnum<{
         unknown: "unknown";
         pending: "pending";
@@ -601,6 +615,8 @@ export declare const refundRoutes: readonly [{
         object: z.ZodLiteral<"settlement">;
         livemode: z.ZodBoolean;
         payment_intent: z.ZodType<string | import("../..").Ref<"payment_intent">, string | import("../..").Ref<"payment_intent">, z.core.$ZodTypeInternals<string | import("../..").Ref<"payment_intent">, string | import("../..").Ref<"payment_intent">>>;
+        refund: z.ZodNullable<z.ZodType<string | import("../..").Ref<"refund">, string | import("../..").Ref<"refund">, z.core.$ZodTypeInternals<string | import("../..").Ref<"refund">, string | import("../..").Ref<"refund">>>>;
+        dispute: z.ZodNullable<z.ZodType<string | import("../..").Ref<"dispute">, string | import("../..").Ref<"dispute">, z.core.$ZodTypeInternals<string | import("../..").Ref<"dispute">, string | import("../..").Ref<"dispute">>>>;
         status: z.ZodEnum<{
             unknown: "unknown";
             pending: "pending";
@@ -615,6 +631,41 @@ export declare const refundRoutes: readonly [{
     }, z.core.$strict>;
     readonly sdk: "refunds.settlement";
     readonly expandable: "settlement";
+}, {
+    readonly operationId: "retrieveRefundSettlement";
+    readonly method: "get";
+    readonly path: "/v1/refunds/{id}/settlement";
+    readonly tag: "Refunds";
+    readonly summary: "Retrieve a refund's settlement";
+    readonly description: "What the refund took off the settlement balance — `gross`, `fee`, a negative `net` — in the settlement currency, read live from the provider. A missing figure is `null` with a `status`, never `0`; a refund that failed or was canceled is `unknown`.";
+    readonly auth: "service";
+    readonly scope: "payments:read";
+    readonly params: {
+        id: string;
+    };
+    readonly query: z.ZodObject<{
+        expand: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>, z.ZodTransform<string[], string | string[]>>, z.ZodArray<z.ZodString>>>;
+    }, z.core.$strict>;
+    readonly response: z.ZodObject<{
+        object: z.ZodLiteral<"settlement">;
+        livemode: z.ZodBoolean;
+        payment_intent: z.ZodType<string | import("../..").Ref<"payment_intent">, string | import("../..").Ref<"payment_intent">, z.core.$ZodTypeInternals<string | import("../..").Ref<"payment_intent">, string | import("../..").Ref<"payment_intent">>>;
+        refund: z.ZodNullable<z.ZodType<string | import("../..").Ref<"refund">, string | import("../..").Ref<"refund">, z.core.$ZodTypeInternals<string | import("../..").Ref<"refund">, string | import("../..").Ref<"refund">>>>;
+        dispute: z.ZodNullable<z.ZodType<string | import("../..").Ref<"dispute">, string | import("../..").Ref<"dispute">, z.core.$ZodTypeInternals<string | import("../..").Ref<"dispute">, string | import("../..").Ref<"dispute">>>>;
+        status: z.ZodEnum<{
+            unknown: "unknown";
+            pending: "pending";
+            available: "available";
+        }>;
+        gross: z.ZodNullable<z.ZodString>;
+        fee: z.ZodNullable<z.ZodString>;
+        net: z.ZodNullable<z.ZodString>;
+        currency: z.ZodNullable<z.ZodString>;
+        available_on: z.ZodNullable<z.ZodNumber>;
+        exchange_rate: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strict>;
+    readonly sdk: "refunds.refundSettlement";
+    readonly expandable: "settlement";
 }, {
     readonly operationId: "searchRefunds";
     readonly method: "get";

package/dist/types/vocabulary/events.d.ts

@@ -146,8 +146,12 @@ export type WebhookEndpointStatus = (typeof WEBHOOK_ENDPOINT_STATUSES)[number];
  *  - `delivery_failures`    — every delivery to it failed for three days
  *    straight, so Peable stopped sending. Re-enabling it (`disabled: false`)
  *    starts the clock again.
+ *  - `url_refused`          — its stored `url` breaks the rules a URL is
+ *    registered under (https in live mode, ports 80/443, no private, loopback
+ *    or reserved address), judged again before every delivery, so Peable never
+ *    sent to it. It is re-enabled only together with a `url` that passes.
  */
-export declare const WEBHOOK_ENDPOINT_DISABLED_REASONS: readonly ["disabled_by_merchant", "delivery_failures"];
+export declare const WEBHOOK_ENDPOINT_DISABLED_REASONS: readonly ["disabled_by_merchant", "delivery_failures", "url_refused"];
 export type WebhookEndpointDisabledReason = (typeof WEBHOOK_ENDPOINT_DISABLED_REASONS)[number];
 /** At most this many endpoints per merchant (per mode). */
 export declare const WEBHOOK_ENDPOINTS_MAX_PER_MERCHANT = 16;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peable.to/contracts",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "The Peable wire, declared once: Zod contracts of every public route, the OpenAPI 3.1 generator and the closed value sets (ADR 0014 D5).",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",