@payclave/sdk-server 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @payclave/sdk-server
 
+## 0.3.0
+
+### Added
+
+- `checkInvoiceRefund`, which asks Payclave's refund policy whether a refund would be accepted before you send it.
+- `recordInvoiceRefundReference` accepts `destinationAddress` and `destinationReason`, and `externalTransactionHash` is optional (omit it in test mode). Refund adjustments include `verificationStatus`, `destinationAddress`, `destinationSource`, `riskFlags`, `senderAddress`, `verifiedAt`, `verificationFailureReason`, and `failedTransactionHash`.
+- `invoice.refund_verified` and `invoice.refund_failed` webhook event types.
+
 ## 0.2.0
 
 ### Changed

package/README.md

@@ -20,9 +20,9 @@ durable retries, and idempotent simulated fulfillment. It uses the published SDK
 ## Install
 
 ```bash
-npm install @payclave/sdk-server@0.2.0
+npm install @payclave/sdk-server@0.3.0
 # or
-bun add @payclave/sdk-server@0.2.0
+bun add @payclave/sdk-server@0.3.0
 ```
 
 ## Create a checkout session
@@ -164,7 +164,7 @@ const issued = await payclave.issueInvoice(draft.id, {
 
 The server calculates line totals and invoice totals at the settlement token's 6-decimal scale. `updateInvoiceDraft` replaces editable commercial fields and requires the latest `version`; `listInvoices` supports `limit`, `startingAfter`, and `collectionState`. Set `reminderSchedule` on the draft to schedule conservative before-due, due-date, and after-due reminders. Passing `send: true` to `issueInvoice` queues the issue email in the same durable workflow; `sendInvoice` resends it and `remindInvoice` queues a manual payment reminder. Invoice detail responses include immutable delivery history and the next scheduled reminder.
 
-For a partially paid invoice, `createInvoiceCheckoutSession` creates or reuses a checkout for the exact server-calculated remainder. Collection actions never move funds: `voidInvoiceRemaining` records the unpaid remainder as a write-off, and `recordInvoiceRefundReference` records a merchant-initiated external transaction without initiating a refund. Issued invoice responses include all checkout sessions, independently verified payments, and adjustment records.
+For a partially paid invoice, `createInvoiceCheckoutSession` creates or reuses a checkout for the exact server-calculated remainder. Collection actions never move funds: `voidInvoiceRemaining` records the unpaid remainder as a write-off, and `recordInvoiceRefundReference` records a refund you sent, from your settlement wallet or another wallet such as an exchange account; Payclave never sends refunds. Call `checkInvoiceRefund` first: it reports whether the refund is allowed, whether it needs a `destinationReason`, and any warnings, such as a destination that is not the wallet the customer paid from or a refund of an overpayment. Where refund verification is available (always in test mode), the recorded adjustment starts as `verificationStatus: "pending"`, and Payclave verifies the transfer onchain before sending `invoice.refund_verified` or `invoice.refund_failed`. Issued invoice responses include all checkout sessions, independently verified payments, and adjustment records.
 
 `downloadInvoicePDF(id)` returns authenticated PDF bytes, a safe filename, and the request ID. The PDF is generated from the API's current server-side invoice snapshot; save or stream the returned bytes from trusted backend code.
 
@@ -245,7 +245,7 @@ The archive contains the versioned manifest, token-separated summary, invoice, p
 
 ### Webhook endpoints
 
-`createWebhookEndpoint` accepts a `url`, optional `eventTypes`, and `signal`. Supported event types are exported as `PAYCLAVE_WEBHOOK_EVENT_TYPES` and include invoice issue, paid, partial, past-due, overpayment, void, uncollectible, refund-reference, expiry, late payment after collection closure, payment-link completion and expiry, and payment failure events.
+`createWebhookEndpoint` accepts a `url`, optional `eventTypes`, and `signal`. Supported event types are exported as `PAYCLAVE_WEBHOOK_EVENT_TYPES` and include invoice issue, paid, partial, past-due, overpayment, void, uncollectible, refund recorded, verified, and failed, expiry, late payment after collection closure, payment-link completion and expiry, and payment failure events.
 
 `getWebhookDelivery` returns the immutable event payload, replay lineage, and complete attempt timeline. Attempts include start/completion timestamps, duration, status, a stable error category, safe request-header evidence, and a sanitized response excerpt capped at 4 KB. `listWebhookDeliveryAttempts` returns that timeline directly. `replayWebhookDelivery` requires an `idempotencyKey`, creates a new delivery linked to the source, and preserves the original event ID and payload. Confirm that your handler deduplicates by event ID before replaying.
 

package/dist/index.cjs

@@ -13,6 +13,8 @@ var PAYCLAVE_WEBHOOK_EVENT_TYPES = [
   "invoice.voided",
   "invoice.uncollectible",
   "invoice.refund_recorded",
+  "invoice.refund_verified",
+  "invoice.refund_failed",
   "invoice.payment_received_after_void",
   "invoice.payment_received_after_uncollectible",
   "invoice.expired",
@@ -180,7 +182,7 @@ var PayclaveError = class extends Error {
   }
 };
 var PAYCLAVE_SERVER_SDK_NAME = "payclave-sdk-server";
-var PAYCLAVE_SERVER_SDK_VERSION = "0.2.0";
+var PAYCLAVE_SERVER_SDK_VERSION = "0.3.0";
 var defaultApiBaseUrl = "https://api.payclave.com";
 var defaultFetcher = (input, init) => fetch(input, init);
 var secretKeyPattern = /^sk_(test|live)_[A-Za-z0-9_-]+$/;
@@ -697,6 +699,7 @@ var isInvoice = (value) => {
 };
 var isInvoiceCheckoutSessionCreated = (value) => isRecord(value) && typeof value.invoiceId === "string" && typeof value.invoiceNumber === "string" && typeof value.checkoutSessionId === "string" && typeof value.checkoutUrl === "string" && typeof value.amountDue === "string" && typeof value.currencyCode === "string" && typeof value.expiresAt === "string";
 var isRefundReferenceResult = (value) => isRecord(value) && isRecord(value.adjustment) && isInvoice(value.invoice);
+var isRefundDecision = (value) => isRecord(value) && typeof value.allowed === "boolean" && typeof value.requiresApproval === "boolean" && typeof value.refundableAmount === "string" && typeof value.overpaidAmount === "string" && Array.isArray(value.warnings);
 var isInvoiceList = (value) => isRecord(value) && Array.isArray(value.items) && value.items.every(isInvoice) && typeof value.hasMore === "boolean" && isStringOrNull(value.nextCursor);
 var isPaymentLinkCollect = (value) => isRecord(value) && typeof value.email === "boolean" && typeof value.name === "boolean" && typeof value.reference === "boolean";
 var isPaymentLink = (value) => isRecord(value) && typeof value.id === "string" && value.object === "payment_link" && typeof value.publicId === "string" && typeof value.url === "string" && typeof value.merchantId === "string" && typeof value.mode === "string" && typeof value.status === "string" && typeof value.version === "number" && typeof value.title === "string" && typeof value.description === "string" && (value.amountType === "fixed" || value.amountType === "customer_entered") && isStringOrNull(value.amount) && isStringOrNull(value.minimumAmount) && isStringOrNull(value.maximumAmount) && typeof value.currencyCode === "string" && typeof value.chainId === "number" && typeof value.tokenContract === "string" && (value.usageType === "single_use" || value.usageType === "reusable") && typeof value.completedPayments === "number" && typeof value.startedCheckouts === "number" && isStringOrNull(value.activeAt) && isStringOrNull(value.expiresAt) && isStringOrNull(value.pausedAt) && isStringOrNull(value.archivedAt) && isPaymentLinkCollect(value.collect) && typeof value.referencePrefix === "string" && isStringOrNull(value.successUrl) && isStringOrNull(value.cancelUrl) && typeof value.successMessage === "string" && isMetadata(value.metadata) && isStringOrNull(value.reservationInvoiceId) && isStringOrNull(value.reservedAt) && typeof value.createdAt === "string" && typeof value.updatedAt === "string" && isStringOrNull(value.lastCheckoutCreatedAt);
@@ -1167,6 +1170,19 @@ function createPayclaveServerClient({
       guard: isRefundReferenceResult
     });
   };
+  const checkInvoiceRefund = (id, input) => {
+    assertIdentifier(id, "Invoice id");
+    assertIdentifier(input.paymentId, "Payment id");
+    assertAmount(input.amount);
+    const { signal, ...body } = input;
+    return request({
+      method: "POST",
+      path: `/v1/invoices/${encodePathSegment(id)}/refund-checks`,
+      body,
+      signal,
+      guard: isRefundDecision
+    });
+  };
   const createPaymentLink = (input) => {
     assertPaymentLinkFields(input);
     return request({
@@ -1594,6 +1610,7 @@ function createPayclaveServerClient({
     voidInvoiceRemaining,
     markInvoiceUncollectible,
     duplicateInvoice,
+    checkInvoiceRefund,
     recordInvoiceRefundReference,
     createPaymentLink,
     listPaymentLinks,

package/dist/index.d.cts

@@ -6,7 +6,7 @@ type PayclavePaymentStatus = "detected" | "validating" | "confirmed" | "failed"
 type PayclaveInvoiceCollectionState = "draft" | "open" | "past_due" | "partially_paid" | "paid" | "void" | "uncollectible" | (string & {});
 type PayclaveMigrationState = "current" | "review_required" | (string & {});
 type PayclaveSourceType = "api" | "dashboard" | "payment_link" | "sdk" | "legacy" | (string & {});
-declare const PAYCLAVE_WEBHOOK_EVENT_TYPES: readonly ["invoice.issued", "invoice.paid", "invoice.partially_paid", "invoice.past_due", "invoice.overpaid", "invoice.voided", "invoice.uncollectible", "invoice.refund_recorded", "invoice.payment_received_after_void", "invoice.payment_received_after_uncollectible", "invoice.expired", "payment_link.completed", "payment_link.expired", "payment.failed", "payment.underpaid", "payment.overpaid"];
+declare const PAYCLAVE_WEBHOOK_EVENT_TYPES: readonly ["invoice.issued", "invoice.paid", "invoice.partially_paid", "invoice.past_due", "invoice.overpaid", "invoice.voided", "invoice.uncollectible", "invoice.refund_recorded", "invoice.refund_verified", "invoice.refund_failed", "invoice.payment_received_after_void", "invoice.payment_received_after_uncollectible", "invoice.expired", "payment_link.completed", "payment_link.expired", "payment.failed", "payment.underpaid", "payment.overpaid"];
 type PayclaveWebhookEventType = (typeof PAYCLAVE_WEBHOOK_EVENT_TYPES)[number];
 type PayclaveWebhookDeliveryStatus = "pending" | "delivering" | "delivered" | "retry_scheduled" | "failed" | (string & {});
 type PayclaveMetadata = Record<string, unknown>;
@@ -148,11 +148,34 @@ type RecordInvoiceRefundReferenceInput = PayclaveRequestOptions & {
     paymentId: string;
     amount: string;
     reason: string;
-    externalTransactionHash: string;
+    /** Omit in test mode; Payclave simulates one. */
+    externalTransactionHash?: string;
     chainId: number;
     tokenContract: string;
+    /** Where the refund was sent. Optional when the payment has a verified paying wallet. */
+    destinationAddress?: string;
+    /** Required when destinationAddress is not the verified paying wallet. */
+    destinationReason?: string;
     idempotencyKey?: string;
 };
+type CheckInvoiceRefundInput = PayclaveRequestOptions & {
+    paymentId: string;
+    amount: string;
+    destinationAddress: string;
+};
+type PayclaveRefundRiskCode = "different_destination" | "repeat_destination" | "overpayment" | "sent_from_other_wallet" | (string & {});
+type PayclaveRefundDecision = {
+    allowed: boolean;
+    blockedReason?: string;
+    requiresApproval: boolean;
+    destinationSource?: "verified_payer" | "provided" | (string & {});
+    refundableAmount: string;
+    overpaidAmount: string;
+    warnings: Array<{
+        code: PayclaveRefundRiskCode;
+        message: string;
+    }>;
+};
 type ListInvoicesInput = PayclaveRequestOptions & {
     limit?: number;
     startingAfter?: string;
@@ -592,6 +615,18 @@ type PayclavePaymentAdjustment = {
     externalTransactionHash?: string;
     chainId?: number;
     tokenContract?: string;
+    /** Refund references only: whether Payclave verified the transfer onchain. */
+    verificationStatus?: "unverified" | "pending" | "verified" | "failed" | (string & {});
+    destinationAddress?: string;
+    destinationSource?: "verified_payer" | "provided" | (string & {});
+    destinationReason?: string;
+    riskFlags?: PayclaveRefundRiskCode[];
+    /** Where a verified refund actually came from. */
+    senderAddress?: string;
+    verifiedAt?: string;
+    verificationFailureReason?: string;
+    /** A failed refund's hash, released so the transfer can be recorded again. */
+    failedTransactionHash?: string;
     createdByType: string;
     createdById: string;
     createdAt: string;
@@ -824,7 +859,7 @@ declare class PayclaveError extends Error {
     };
 }
 declare const PAYCLAVE_SERVER_SDK_NAME = "payclave-sdk-server";
-declare const PAYCLAVE_SERVER_SDK_VERSION = "0.2.0";
+declare const PAYCLAVE_SERVER_SDK_VERSION = "0.3.0";
 declare function assertPayclaveWebhookSignature({ payload, signature, secret, toleranceSeconds, now, }: VerifyWebhookSignatureInput): void;
 declare function verifyPayclaveWebhookSignature(input: VerifyWebhookSignatureInput): boolean;
 declare function constructPayclaveWebhookEvent<TData extends PayclaveWebhookData = PayclaveWebhookData>(input: VerifyWebhookSignatureInput): PayclaveWebhookEvent<TData>;
@@ -845,6 +880,7 @@ declare function createPayclaveServerClient({ secretKey, apiBaseUrl, fetcher, ti
     voidInvoiceRemaining: (id: string, input?: InvoiceActionInput) => Promise<PayclaveInvoice>;
     markInvoiceUncollectible: (id: string, input?: InvoiceActionInput) => Promise<PayclaveInvoice>;
     duplicateInvoice: (id: string, input?: CreateInvoiceCheckoutSessionInput) => Promise<PayclaveInvoice>;
+    checkInvoiceRefund: (id: string, input: CheckInvoiceRefundInput) => Promise<PayclaveRefundDecision>;
     recordInvoiceRefundReference: (id: string, input: RecordInvoiceRefundReferenceInput) => Promise<PayclaveRefundReferenceResult>;
     createPaymentLink: (input: CreatePaymentLinkInput) => Promise<PayclavePaymentLink>;
     listPaymentLinks: (input?: ListPaymentLinksInput) => Promise<PayclavePaymentLinkList>;
@@ -885,4 +921,5 @@ declare function createPayclaveServerClient({ secretKey, apiBaseUrl, fetcher, ti
 };
 type PayclaveServerClient = ReturnType<typeof createPayclaveServerClient>;
 
-export { type CreateCheckoutSessionInput, type CreateInvoiceCheckoutSessionInput, type CreateInvoiceDraftInput, type CreateInvoiceInput, type CreatePaymentLinkInput, type CreateReconciliationExportInput, type CreateTestWebhookInput, type CreateWebhookEndpointInput, type GetReconciliationSummaryInput, type InvoiceActionInput, type IssueInvoiceInput, type ListInvoicesInput, type ListPaymentLinkPaymentsInput, type ListPaymentLinksInput, type ListReconciliationExportsInput, type ListWebhookDeliveriesInput, type ListWebhookIncidentsInput, PAYCLAVE_API_ERROR_CODES, PAYCLAVE_RECONCILIATION_SCHEMA_VERSION, PAYCLAVE_SERVER_SDK_ERROR_CODES, PAYCLAVE_SERVER_SDK_NAME, PAYCLAVE_SERVER_SDK_VERSION, PAYCLAVE_WEBHOOK_EVENT_TYPES, PAYCLAVE_WEBHOOK_VERIFICATION_ERROR_CODES, type PayclaveApiErrorCode, type PayclaveCheckoutSession, type PayclaveCreatedCheckoutSession, PayclaveError, type PayclaveErrorCode, type PayclaveFetcher, type PayclaveInvoice, type PayclaveInvoiceActivityEvent, type PayclaveInvoiceCheckoutSession, type PayclaveInvoiceCheckoutSessionCreated, type PayclaveInvoiceCollectionState, type PayclaveInvoiceCustomer, type PayclaveInvoiceDelivery, type PayclaveInvoiceDiscountInput, type PayclaveInvoiceDraftFields, type PayclaveInvoiceLineInput, type PayclaveInvoiceList, type PayclaveInvoicePDF, type PayclaveInvoicePayment, type PayclaveInvoiceReminderSchedule, type PayclaveInvoiceStatus, type PayclaveInvoiceTaxInput, type PayclaveMetadata, type PayclaveMigrationState, type PayclaveMode, type PayclavePayment, type PayclavePaymentAdjustment, type PayclavePaymentLink, type PayclavePaymentLinkAmountType, type PayclavePaymentLinkCollect, type PayclavePaymentLinkFields, type PayclavePaymentLinkList, type PayclavePaymentLinkPayments, type PayclavePaymentLinkStatus, type PayclavePaymentLinkUsageType, type PayclavePaymentSource, type PayclavePaymentStatus, type PayclaveReconciliationDateBasis, type PayclaveReconciliationDownload, type PayclaveReconciliationExport, type PayclaveReconciliationExportList, type PayclaveReconciliationExportStatus, type PayclaveReconciliationFile, type PayclaveReconciliationFilters, type PayclaveReconciliationSchema, type PayclaveReconciliationSummary, type PayclaveReconciliationTokenSummary, type PayclaveRefundReferenceResult, type PayclaveRequestOptions, type PayclaveServerClient, type PayclaveServerClientOptions, type PayclaveServerSdkErrorCode, type PayclaveSourceType, type PayclaveWebhookData, type PayclaveWebhookDelivery, type PayclaveWebhookDeliveryAttempt, type PayclaveWebhookDeliveryAttemptSummary, type PayclaveWebhookDeliveryStatus, type PayclaveWebhookEndpoint, type PayclaveWebhookEvent, type PayclaveWebhookEventType, type PayclaveWebhookIncident, type PayclaveWebhookSecretVersion, type PayclaveWebhookVerificationErrorCode, type PaymentLinkActionInput, type ReconciliationExportActionInput, type RecordInvoiceRefundReferenceInput, type ReleasePaymentLinkReservationInput, type ReplayWebhookDeliveryInput, type UpdateInvoiceDraftInput, type UpdatePaymentLinkInput, type UpdateWebhookEndpointInput, type VerifyWebhookSignatureInput, type WebhookEndpointActionInput, assertPayclaveWebhookSignature, constructPayclaveWebhookEvent, createPayclaveServerClient, verifyPayclaveWebhookSignature };
+export { PAYCLAVE_API_ERROR_CODES, PAYCLAVE_RECONCILIATION_SCHEMA_VERSION, PAYCLAVE_SERVER_SDK_ERROR_CODES, PAYCLAVE_SERVER_SDK_NAME, PAYCLAVE_SERVER_SDK_VERSION, PAYCLAVE_WEBHOOK_EVENT_TYPES, PAYCLAVE_WEBHOOK_VERIFICATION_ERROR_CODES, PayclaveError, assertPayclaveWebhookSignature, constructPayclaveWebhookEvent, createPayclaveServerClient, verifyPayclaveWebhookSignature };
+export type { CheckInvoiceRefundInput, CreateCheckoutSessionInput, CreateInvoiceCheckoutSessionInput, CreateInvoiceDraftInput, CreateInvoiceInput, CreatePaymentLinkInput, CreateReconciliationExportInput, CreateTestWebhookInput, CreateWebhookEndpointInput, GetReconciliationSummaryInput, InvoiceActionInput, IssueInvoiceInput, ListInvoicesInput, ListPaymentLinkPaymentsInput, ListPaymentLinksInput, ListReconciliationExportsInput, ListWebhookDeliveriesInput, ListWebhookIncidentsInput, PayclaveApiErrorCode, PayclaveCheckoutSession, PayclaveCreatedCheckoutSession, PayclaveErrorCode, PayclaveFetcher, PayclaveInvoice, PayclaveInvoiceActivityEvent, PayclaveInvoiceCheckoutSession, PayclaveInvoiceCheckoutSessionCreated, PayclaveInvoiceCollectionState, PayclaveInvoiceCustomer, PayclaveInvoiceDelivery, PayclaveInvoiceDiscountInput, PayclaveInvoiceDraftFields, PayclaveInvoiceLineInput, PayclaveInvoiceList, PayclaveInvoicePDF, PayclaveInvoicePayment, PayclaveInvoiceReminderSchedule, PayclaveInvoiceStatus, PayclaveInvoiceTaxInput, PayclaveMetadata, PayclaveMigrationState, PayclaveMode, PayclavePayment, PayclavePaymentAdjustment, PayclavePaymentLink, PayclavePaymentLinkAmountType, PayclavePaymentLinkCollect, PayclavePaymentLinkFields, PayclavePaymentLinkList, PayclavePaymentLinkPayments, PayclavePaymentLinkStatus, PayclavePaymentLinkUsageType, PayclavePaymentSource, PayclavePaymentStatus, PayclaveReconciliationDateBasis, PayclaveReconciliationDownload, PayclaveReconciliationExport, PayclaveReconciliationExportList, PayclaveReconciliationExportStatus, PayclaveReconciliationFile, PayclaveReconciliationFilters, PayclaveReconciliationSchema, PayclaveReconciliationSummary, PayclaveReconciliationTokenSummary, PayclaveRefundDecision, PayclaveRefundReferenceResult, PayclaveRefundRiskCode, PayclaveRequestOptions, PayclaveServerClient, PayclaveServerClientOptions, PayclaveServerSdkErrorCode, PayclaveSourceType, PayclaveWebhookData, PayclaveWebhookDelivery, PayclaveWebhookDeliveryAttempt, PayclaveWebhookDeliveryAttemptSummary, PayclaveWebhookDeliveryStatus, PayclaveWebhookEndpoint, PayclaveWebhookEvent, PayclaveWebhookEventType, PayclaveWebhookIncident, PayclaveWebhookSecretVersion, PayclaveWebhookVerificationErrorCode, PaymentLinkActionInput, ReconciliationExportActionInput, RecordInvoiceRefundReferenceInput, ReleasePaymentLinkReservationInput, ReplayWebhookDeliveryInput, UpdateInvoiceDraftInput, UpdatePaymentLinkInput, UpdateWebhookEndpointInput, VerifyWebhookSignatureInput, WebhookEndpointActionInput };

package/dist/index.d.ts

@@ -6,7 +6,7 @@ type PayclavePaymentStatus = "detected" | "validating" | "confirmed" | "failed"
 type PayclaveInvoiceCollectionState = "draft" | "open" | "past_due" | "partially_paid" | "paid" | "void" | "uncollectible" | (string & {});
 type PayclaveMigrationState = "current" | "review_required" | (string & {});
 type PayclaveSourceType = "api" | "dashboard" | "payment_link" | "sdk" | "legacy" | (string & {});
-declare const PAYCLAVE_WEBHOOK_EVENT_TYPES: readonly ["invoice.issued", "invoice.paid", "invoice.partially_paid", "invoice.past_due", "invoice.overpaid", "invoice.voided", "invoice.uncollectible", "invoice.refund_recorded", "invoice.payment_received_after_void", "invoice.payment_received_after_uncollectible", "invoice.expired", "payment_link.completed", "payment_link.expired", "payment.failed", "payment.underpaid", "payment.overpaid"];
+declare const PAYCLAVE_WEBHOOK_EVENT_TYPES: readonly ["invoice.issued", "invoice.paid", "invoice.partially_paid", "invoice.past_due", "invoice.overpaid", "invoice.voided", "invoice.uncollectible", "invoice.refund_recorded", "invoice.refund_verified", "invoice.refund_failed", "invoice.payment_received_after_void", "invoice.payment_received_after_uncollectible", "invoice.expired", "payment_link.completed", "payment_link.expired", "payment.failed", "payment.underpaid", "payment.overpaid"];
 type PayclaveWebhookEventType = (typeof PAYCLAVE_WEBHOOK_EVENT_TYPES)[number];
 type PayclaveWebhookDeliveryStatus = "pending" | "delivering" | "delivered" | "retry_scheduled" | "failed" | (string & {});
 type PayclaveMetadata = Record<string, unknown>;
@@ -148,11 +148,34 @@ type RecordInvoiceRefundReferenceInput = PayclaveRequestOptions & {
     paymentId: string;
     amount: string;
     reason: string;
-    externalTransactionHash: string;
+    /** Omit in test mode; Payclave simulates one. */
+    externalTransactionHash?: string;
     chainId: number;
     tokenContract: string;
+    /** Where the refund was sent. Optional when the payment has a verified paying wallet. */
+    destinationAddress?: string;
+    /** Required when destinationAddress is not the verified paying wallet. */
+    destinationReason?: string;
     idempotencyKey?: string;
 };
+type CheckInvoiceRefundInput = PayclaveRequestOptions & {
+    paymentId: string;
+    amount: string;
+    destinationAddress: string;
+};
+type PayclaveRefundRiskCode = "different_destination" | "repeat_destination" | "overpayment" | "sent_from_other_wallet" | (string & {});
+type PayclaveRefundDecision = {
+    allowed: boolean;
+    blockedReason?: string;
+    requiresApproval: boolean;
+    destinationSource?: "verified_payer" | "provided" | (string & {});
+    refundableAmount: string;
+    overpaidAmount: string;
+    warnings: Array<{
+        code: PayclaveRefundRiskCode;
+        message: string;
+    }>;
+};
 type ListInvoicesInput = PayclaveRequestOptions & {
     limit?: number;
     startingAfter?: string;
@@ -592,6 +615,18 @@ type PayclavePaymentAdjustment = {
     externalTransactionHash?: string;
     chainId?: number;
     tokenContract?: string;
+    /** Refund references only: whether Payclave verified the transfer onchain. */
+    verificationStatus?: "unverified" | "pending" | "verified" | "failed" | (string & {});
+    destinationAddress?: string;
+    destinationSource?: "verified_payer" | "provided" | (string & {});
+    destinationReason?: string;
+    riskFlags?: PayclaveRefundRiskCode[];
+    /** Where a verified refund actually came from. */
+    senderAddress?: string;
+    verifiedAt?: string;
+    verificationFailureReason?: string;
+    /** A failed refund's hash, released so the transfer can be recorded again. */
+    failedTransactionHash?: string;
     createdByType: string;
     createdById: string;
     createdAt: string;
@@ -824,7 +859,7 @@ declare class PayclaveError extends Error {
     };
 }
 declare const PAYCLAVE_SERVER_SDK_NAME = "payclave-sdk-server";
-declare const PAYCLAVE_SERVER_SDK_VERSION = "0.2.0";
+declare const PAYCLAVE_SERVER_SDK_VERSION = "0.3.0";
 declare function assertPayclaveWebhookSignature({ payload, signature, secret, toleranceSeconds, now, }: VerifyWebhookSignatureInput): void;
 declare function verifyPayclaveWebhookSignature(input: VerifyWebhookSignatureInput): boolean;
 declare function constructPayclaveWebhookEvent<TData extends PayclaveWebhookData = PayclaveWebhookData>(input: VerifyWebhookSignatureInput): PayclaveWebhookEvent<TData>;
@@ -845,6 +880,7 @@ declare function createPayclaveServerClient({ secretKey, apiBaseUrl, fetcher, ti
     voidInvoiceRemaining: (id: string, input?: InvoiceActionInput) => Promise<PayclaveInvoice>;
     markInvoiceUncollectible: (id: string, input?: InvoiceActionInput) => Promise<PayclaveInvoice>;
     duplicateInvoice: (id: string, input?: CreateInvoiceCheckoutSessionInput) => Promise<PayclaveInvoice>;
+    checkInvoiceRefund: (id: string, input: CheckInvoiceRefundInput) => Promise<PayclaveRefundDecision>;
     recordInvoiceRefundReference: (id: string, input: RecordInvoiceRefundReferenceInput) => Promise<PayclaveRefundReferenceResult>;
     createPaymentLink: (input: CreatePaymentLinkInput) => Promise<PayclavePaymentLink>;
     listPaymentLinks: (input?: ListPaymentLinksInput) => Promise<PayclavePaymentLinkList>;
@@ -885,4 +921,5 @@ declare function createPayclaveServerClient({ secretKey, apiBaseUrl, fetcher, ti
 };
 type PayclaveServerClient = ReturnType<typeof createPayclaveServerClient>;
 
-export { type CreateCheckoutSessionInput, type CreateInvoiceCheckoutSessionInput, type CreateInvoiceDraftInput, type CreateInvoiceInput, type CreatePaymentLinkInput, type CreateReconciliationExportInput, type CreateTestWebhookInput, type CreateWebhookEndpointInput, type GetReconciliationSummaryInput, type InvoiceActionInput, type IssueInvoiceInput, type ListInvoicesInput, type ListPaymentLinkPaymentsInput, type ListPaymentLinksInput, type ListReconciliationExportsInput, type ListWebhookDeliveriesInput, type ListWebhookIncidentsInput, PAYCLAVE_API_ERROR_CODES, PAYCLAVE_RECONCILIATION_SCHEMA_VERSION, PAYCLAVE_SERVER_SDK_ERROR_CODES, PAYCLAVE_SERVER_SDK_NAME, PAYCLAVE_SERVER_SDK_VERSION, PAYCLAVE_WEBHOOK_EVENT_TYPES, PAYCLAVE_WEBHOOK_VERIFICATION_ERROR_CODES, type PayclaveApiErrorCode, type PayclaveCheckoutSession, type PayclaveCreatedCheckoutSession, PayclaveError, type PayclaveErrorCode, type PayclaveFetcher, type PayclaveInvoice, type PayclaveInvoiceActivityEvent, type PayclaveInvoiceCheckoutSession, type PayclaveInvoiceCheckoutSessionCreated, type PayclaveInvoiceCollectionState, type PayclaveInvoiceCustomer, type PayclaveInvoiceDelivery, type PayclaveInvoiceDiscountInput, type PayclaveInvoiceDraftFields, type PayclaveInvoiceLineInput, type PayclaveInvoiceList, type PayclaveInvoicePDF, type PayclaveInvoicePayment, type PayclaveInvoiceReminderSchedule, type PayclaveInvoiceStatus, type PayclaveInvoiceTaxInput, type PayclaveMetadata, type PayclaveMigrationState, type PayclaveMode, type PayclavePayment, type PayclavePaymentAdjustment, type PayclavePaymentLink, type PayclavePaymentLinkAmountType, type PayclavePaymentLinkCollect, type PayclavePaymentLinkFields, type PayclavePaymentLinkList, type PayclavePaymentLinkPayments, type PayclavePaymentLinkStatus, type PayclavePaymentLinkUsageType, type PayclavePaymentSource, type PayclavePaymentStatus, type PayclaveReconciliationDateBasis, type PayclaveReconciliationDownload, type PayclaveReconciliationExport, type PayclaveReconciliationExportList, type PayclaveReconciliationExportStatus, type PayclaveReconciliationFile, type PayclaveReconciliationFilters, type PayclaveReconciliationSchema, type PayclaveReconciliationSummary, type PayclaveReconciliationTokenSummary, type PayclaveRefundReferenceResult, type PayclaveRequestOptions, type PayclaveServerClient, type PayclaveServerClientOptions, type PayclaveServerSdkErrorCode, type PayclaveSourceType, type PayclaveWebhookData, type PayclaveWebhookDelivery, type PayclaveWebhookDeliveryAttempt, type PayclaveWebhookDeliveryAttemptSummary, type PayclaveWebhookDeliveryStatus, type PayclaveWebhookEndpoint, type PayclaveWebhookEvent, type PayclaveWebhookEventType, type PayclaveWebhookIncident, type PayclaveWebhookSecretVersion, type PayclaveWebhookVerificationErrorCode, type PaymentLinkActionInput, type ReconciliationExportActionInput, type RecordInvoiceRefundReferenceInput, type ReleasePaymentLinkReservationInput, type ReplayWebhookDeliveryInput, type UpdateInvoiceDraftInput, type UpdatePaymentLinkInput, type UpdateWebhookEndpointInput, type VerifyWebhookSignatureInput, type WebhookEndpointActionInput, assertPayclaveWebhookSignature, constructPayclaveWebhookEvent, createPayclaveServerClient, verifyPayclaveWebhookSignature };
+export { PAYCLAVE_API_ERROR_CODES, PAYCLAVE_RECONCILIATION_SCHEMA_VERSION, PAYCLAVE_SERVER_SDK_ERROR_CODES, PAYCLAVE_SERVER_SDK_NAME, PAYCLAVE_SERVER_SDK_VERSION, PAYCLAVE_WEBHOOK_EVENT_TYPES, PAYCLAVE_WEBHOOK_VERIFICATION_ERROR_CODES, PayclaveError, assertPayclaveWebhookSignature, constructPayclaveWebhookEvent, createPayclaveServerClient, verifyPayclaveWebhookSignature };
+export type { CheckInvoiceRefundInput, CreateCheckoutSessionInput, CreateInvoiceCheckoutSessionInput, CreateInvoiceDraftInput, CreateInvoiceInput, CreatePaymentLinkInput, CreateReconciliationExportInput, CreateTestWebhookInput, CreateWebhookEndpointInput, GetReconciliationSummaryInput, InvoiceActionInput, IssueInvoiceInput, ListInvoicesInput, ListPaymentLinkPaymentsInput, ListPaymentLinksInput, ListReconciliationExportsInput, ListWebhookDeliveriesInput, ListWebhookIncidentsInput, PayclaveApiErrorCode, PayclaveCheckoutSession, PayclaveCreatedCheckoutSession, PayclaveErrorCode, PayclaveFetcher, PayclaveInvoice, PayclaveInvoiceActivityEvent, PayclaveInvoiceCheckoutSession, PayclaveInvoiceCheckoutSessionCreated, PayclaveInvoiceCollectionState, PayclaveInvoiceCustomer, PayclaveInvoiceDelivery, PayclaveInvoiceDiscountInput, PayclaveInvoiceDraftFields, PayclaveInvoiceLineInput, PayclaveInvoiceList, PayclaveInvoicePDF, PayclaveInvoicePayment, PayclaveInvoiceReminderSchedule, PayclaveInvoiceStatus, PayclaveInvoiceTaxInput, PayclaveMetadata, PayclaveMigrationState, PayclaveMode, PayclavePayment, PayclavePaymentAdjustment, PayclavePaymentLink, PayclavePaymentLinkAmountType, PayclavePaymentLinkCollect, PayclavePaymentLinkFields, PayclavePaymentLinkList, PayclavePaymentLinkPayments, PayclavePaymentLinkStatus, PayclavePaymentLinkUsageType, PayclavePaymentSource, PayclavePaymentStatus, PayclaveReconciliationDateBasis, PayclaveReconciliationDownload, PayclaveReconciliationExport, PayclaveReconciliationExportList, PayclaveReconciliationExportStatus, PayclaveReconciliationFile, PayclaveReconciliationFilters, PayclaveReconciliationSchema, PayclaveReconciliationSummary, PayclaveReconciliationTokenSummary, PayclaveRefundDecision, PayclaveRefundReferenceResult, PayclaveRefundRiskCode, PayclaveRequestOptions, PayclaveServerClient, PayclaveServerClientOptions, PayclaveServerSdkErrorCode, PayclaveSourceType, PayclaveWebhookData, PayclaveWebhookDelivery, PayclaveWebhookDeliveryAttempt, PayclaveWebhookDeliveryAttemptSummary, PayclaveWebhookDeliveryStatus, PayclaveWebhookEndpoint, PayclaveWebhookEvent, PayclaveWebhookEventType, PayclaveWebhookIncident, PayclaveWebhookSecretVersion, PayclaveWebhookVerificationErrorCode, PaymentLinkActionInput, ReconciliationExportActionInput, RecordInvoiceRefundReferenceInput, ReleasePaymentLinkReservationInput, ReplayWebhookDeliveryInput, UpdateInvoiceDraftInput, UpdatePaymentLinkInput, UpdateWebhookEndpointInput, VerifyWebhookSignatureInput, WebhookEndpointActionInput };

package/dist/index.js

@@ -11,6 +11,8 @@ var PAYCLAVE_WEBHOOK_EVENT_TYPES = [
   "invoice.voided",
   "invoice.uncollectible",
   "invoice.refund_recorded",
+  "invoice.refund_verified",
+  "invoice.refund_failed",
   "invoice.payment_received_after_void",
   "invoice.payment_received_after_uncollectible",
   "invoice.expired",
@@ -178,7 +180,7 @@ var PayclaveError = class extends Error {
   }
 };
 var PAYCLAVE_SERVER_SDK_NAME = "payclave-sdk-server";
-var PAYCLAVE_SERVER_SDK_VERSION = "0.2.0";
+var PAYCLAVE_SERVER_SDK_VERSION = "0.3.0";
 var defaultApiBaseUrl = "https://api.payclave.com";
 var defaultFetcher = (input, init) => fetch(input, init);
 var secretKeyPattern = /^sk_(test|live)_[A-Za-z0-9_-]+$/;
@@ -695,6 +697,7 @@ var isInvoice = (value) => {
 };
 var isInvoiceCheckoutSessionCreated = (value) => isRecord(value) && typeof value.invoiceId === "string" && typeof value.invoiceNumber === "string" && typeof value.checkoutSessionId === "string" && typeof value.checkoutUrl === "string" && typeof value.amountDue === "string" && typeof value.currencyCode === "string" && typeof value.expiresAt === "string";
 var isRefundReferenceResult = (value) => isRecord(value) && isRecord(value.adjustment) && isInvoice(value.invoice);
+var isRefundDecision = (value) => isRecord(value) && typeof value.allowed === "boolean" && typeof value.requiresApproval === "boolean" && typeof value.refundableAmount === "string" && typeof value.overpaidAmount === "string" && Array.isArray(value.warnings);
 var isInvoiceList = (value) => isRecord(value) && Array.isArray(value.items) && value.items.every(isInvoice) && typeof value.hasMore === "boolean" && isStringOrNull(value.nextCursor);
 var isPaymentLinkCollect = (value) => isRecord(value) && typeof value.email === "boolean" && typeof value.name === "boolean" && typeof value.reference === "boolean";
 var isPaymentLink = (value) => isRecord(value) && typeof value.id === "string" && value.object === "payment_link" && typeof value.publicId === "string" && typeof value.url === "string" && typeof value.merchantId === "string" && typeof value.mode === "string" && typeof value.status === "string" && typeof value.version === "number" && typeof value.title === "string" && typeof value.description === "string" && (value.amountType === "fixed" || value.amountType === "customer_entered") && isStringOrNull(value.amount) && isStringOrNull(value.minimumAmount) && isStringOrNull(value.maximumAmount) && typeof value.currencyCode === "string" && typeof value.chainId === "number" && typeof value.tokenContract === "string" && (value.usageType === "single_use" || value.usageType === "reusable") && typeof value.completedPayments === "number" && typeof value.startedCheckouts === "number" && isStringOrNull(value.activeAt) && isStringOrNull(value.expiresAt) && isStringOrNull(value.pausedAt) && isStringOrNull(value.archivedAt) && isPaymentLinkCollect(value.collect) && typeof value.referencePrefix === "string" && isStringOrNull(value.successUrl) && isStringOrNull(value.cancelUrl) && typeof value.successMessage === "string" && isMetadata(value.metadata) && isStringOrNull(value.reservationInvoiceId) && isStringOrNull(value.reservedAt) && typeof value.createdAt === "string" && typeof value.updatedAt === "string" && isStringOrNull(value.lastCheckoutCreatedAt);
@@ -1165,6 +1168,19 @@ function createPayclaveServerClient({
       guard: isRefundReferenceResult
     });
   };
+  const checkInvoiceRefund = (id, input) => {
+    assertIdentifier(id, "Invoice id");
+    assertIdentifier(input.paymentId, "Payment id");
+    assertAmount(input.amount);
+    const { signal, ...body } = input;
+    return request({
+      method: "POST",
+      path: `/v1/invoices/${encodePathSegment(id)}/refund-checks`,
+      body,
+      signal,
+      guard: isRefundDecision
+    });
+  };
   const createPaymentLink = (input) => {
     assertPaymentLinkFields(input);
     return request({
@@ -1592,6 +1608,7 @@ function createPayclaveServerClient({
     voidInvoiceRemaining,
     markInvoiceUncollectible,
     duplicateInvoice,
+    checkInvoiceRefund,
     recordInvoiceRefundReference,
     createPaymentLink,
     listPaymentLinks,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payclave/sdk-server",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "TypeScript server SDK for Payclave non-custodial crypto checkout.",
   "keywords": [
     "payclave",
@@ -52,9 +52,9 @@
     "prepublishOnly": "bun run lint && bun run typecheck && bun run test && bun run build && bun run pack:check"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.15",
-    "bun-types": "^1.3.14",
-    "tsup": "^8.5.1",
+    "@biomejs/biome": "^2.6.4",
+    "bun-types": "^1.4.4",
+    "tsup": "^9.0.0",
     "typescript": "^6.0.3"
   }
 }