--- updatedAt: 2026-09-30T17:50:34.072Z --- Fetch the complete documentation index at: https://docs.avvio.xyz/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version. # Changelog What changed in each released version, generated at build time from the frozen spec snapshots and the package's changelog, so this page cannot fall behind the contract. Additions are safe to ignore; a removal breaks a generated client. [Environments & sandbox](/environments/) has the versioning and deprecation policy. ## Payouts API The version a client pins is `info.version` in [partner-payouts.openapi.yaml](/partner-payouts.openapi.yaml). Newest first. ### 2026-09-30.1 (unreleased) Documented responses: 34 added, 0 removed - Added `listCorridors -> 400` - Added `listPaymentReasons -> 400` - Added `listBeneficiaries -> 400` - Added `addBeneficiaryMethod -> 404` - Added `deleteBeneficiary -> 400` - Added `deleteBeneficiaryMethod -> 400` - Added `pricePayout -> 404` - Added `pricePayout -> 422` - Added `sendPayout -> 500` - Added `createPayout -> 404` - Added `createPayout -> 500` - Added `createPayoutBatch -> 500` - Added `listPayoutBatches -> 400` - Added `listPayoutBatchItems -> 400` - Added `confirmPayoutBatch -> 400` - Added `cancelPayoutBatch -> 400` - Added `createPayoutLink -> 400` - Added `createPayoutLink -> 503` - Added `submitPayoutLink -> 503` - Added `listBalanceTransactions -> 400` - Added `cancelPayout -> 404` - Added `cancelPayout -> 409` - Added `getPayoutFunding -> 400` - Added `getPayoutFunding -> 404` - Added `getPayoutFunding -> 501` - Added `confirmPayoutFunding -> 404` - Added `confirmPayoutFunding -> 409` - Added `confirmPayoutFunding -> 500` - Added `fundSandbox -> 400` - Added `createSandboxWebhookEndpoint -> 400` - Added `listSandboxWebhookDeliveries -> 400` - Added `listPayouts -> 400` - Added `listPayouts -> 503` - Added `getFundingAccounts -> 503` Schema fields: 14 added, 0 removed - Added `RegEDisclosure.kind` - Added `RegEDisclosure.estimated` - Added `RegEDisclosure.lines` - Added `RegEDisclosure.otherFeesDisclaimer` - Added `Beneficiary.screeningStatus` - Added `Beneficiary.screeningReason` - Added `Beneficiary.screenedAt` - Added `Beneficiary.deletedAt` - Added `WebhookPayout.fee` - Added `WebhookPayout.endUserId` - Added `Error.originalBatchId` - Added `Error.originalRequestId` - Added `Error.existingRecipientId` - Added `Error.existingMethodId` Enum values: 20 added, 19 removed - Removed `parameters.AllowDuplicate = true` - Removed `schemas.PaymentReason = charitable_contributions` - Removed `schemas.PaymentReason = education_fees` - Removed `schemas.PaymentReason = employee_salaries_or_wages` - Removed `schemas.PaymentReason = gifts` - Removed `schemas.PaymentReason = investments` - Removed `schemas.PaymentReason = purchase_of_goods` - Removed `schemas.PaymentReason = purchase_of_services` - Removed `schemas.PaymentReason = personal_transfers` - Removed `schemas.PaymentReason = rent` - Removed `schemas.PaymentReason = loans` - Removed `schemas.PaymentReason = utility_bills` - Removed `schemas.PaymentReason = family_support` - Removed `schemas.PaymentReason = friends_support` - Removed `schemas.PaymentReason = real_estate` - Removed `schemas.PaymentReason = insurance` - Removed `schemas.PaymentReason = intercompany_transfer` - Removed `schemas.PaymentReason = taxes` - Removed `schemas.PaymentReason = travel` - Added `/recipients/{orgId}/{recipientId}/methods/{methodId}/details.get.responses.200.kind = fiat` - Added `/recipients/{orgId}/{recipientId}/methods/{methodId}/details.get.responses.200.kind = crypto` - Added `/payments/organizations/{orgId}/balance/history.get.responses.200.entries.type = funding` - Added `/payments/organizations/{orgId}/balance/history.get.responses.200.entries.type = payout` - Added `/payments/organizations/{orgId}/balance/history.get.responses.200.entries.type = reversal` - Added `/payments/organizations/{orgId}/balance/history.get.responses.200.entries.status = COMPLETED` - Added `/payments/organizations/{orgId}/balance/history.get.responses.200.entries.status = DEBITED` - Added `/payments/organizations/{orgId}/balance/history.get.responses.200.entries.status = RETURNED` - Added `/payments/organizations/{orgId}/balance/history.get.responses.200.entries.status = CANCELED` - Added `schemas.RegEDisclosure.kind = prepayment` - Added `schemas.RegEDisclosure.kind = receipt` - Added `schemas.RegEDisclosure.lines.sign = +` - Added `schemas.RegEDisclosure.lines.sign = -` - Added `schemas.Beneficiary.paymentMethods.kind = fiat` - Added `schemas.Beneficiary.paymentMethods.kind = crypto` - Added `schemas.Beneficiary.paymentMethods.status = active` - Added `schemas.Beneficiary.paymentMethods.status = pending` - Added `schemas.Beneficiary.paymentMethods.status = failed` - Added `schemas.FundingAccount.settlesTo = provider_balance` - Added `schemas.FundingAccount.settlesTo = wallet` ### 2026-09-28.2 Documented responses: - Added `getBalanceHistory -> 400` - Added `getBalanceHistory -> 413` ### 2026-09-28.1 Documented responses: - Added `createBeneficiary -> 422` ### 2026-09-25.2 No operation, response, field or enum changed; descriptions and examples only. ### 2026-09-25.1 Enum values: - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints.post.events = payout_approval.pending` - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints.post.events = payout_approval.approved` - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints.post.events = payout_approval.rejected` - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints.post.events = payout_approval.expired` - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints.post.events = payout_approval.executed` - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints.post.events = payout_approval.execution_failed` ### 2026-09-22.1 No operation, response, field or enum changed; descriptions and examples only. ### 2026-09-21.1 Enum values: - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints.post.events = checkout_payment.partially_refunded` - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints/{endpointId}/deliveries.get.responses.200.eventType = checkout_payment.partially_refunded` - Added `schemas.PayoutEventType = checkout_payment.partially_refunded` ### 2026-09-13.1 Operations: 20 added, 0 removed - Added `GET /organizations/{organizationId}/webhook-endpoints (listWebhookEndpoints)` - Added `GET /organizations/{organizationId}/webhook-endpoints/{endpointId}/deliveries (listWebhookDeliveries)` - Added `GET /payments/organizations/{orgId}/payment-reasons (listPaymentReasons)` - Added `GET /payments/organizations/{orgId}/policy (getPolicy)` - Added `GET /recipients/{orgId}/external/{externalId} (getBeneficiaryByExternalId)` - Added `GET /recipients/{orgId}/{recipientId} (getBeneficiary)` - Added `PATCH /recipients/{orgId}/{recipientId} (updateBeneficiary)` - Added `DELETE /recipients/{orgId}/{recipientId} (deleteBeneficiary)` - Added `DELETE /recipients/{orgId}/{recipientId}/methods/{methodId} (deleteBeneficiaryMethod)` - Added `GET /recipients/{orgId}/{recipientId}/methods/{methodId}/details (getBeneficiaryMethodDetails)` - Added `POST /payments/organizations/{orgId}/payouts/batches (createPayoutBatch)` - Added `GET /payments/organizations/{orgId}/payouts/batches (listPayoutBatches)` - Added `GET /payments/organizations/{orgId}/payouts/batches/{batchId} (getPayoutBatch)` - Added `GET /payments/organizations/{orgId}/payouts/batches/{batchId}/items (listPayoutBatchItems)` - Added `POST /payments/organizations/{orgId}/payouts/batches/{batchId}/confirm (confirmPayoutBatch)` - Added `POST /payments/organizations/{orgId}/payouts/batches/{batchId}/cancel (cancelPayoutBatch)` - Added `GET /payments/organizations/{orgId}/payouts/approvals (listPayoutApprovals)` - Added `GET /payments/organizations/{orgId}/payouts/approvals/{approvalId} (getPayoutApproval)` - Added `GET /payments/organizations/{orgId}/balance_transactions (listBalanceTransactions)` - Added `GET /payments/organizations/{orgId}/audit-events (listAuditEvents)` Documented responses: 143 added, 0 removed - Added `listWebhookEndpoints -> 200` - Added `listWebhookEndpoints -> 401` - Added `listWebhookEndpoints -> 403` - Added `listWebhookEndpoints -> 429` - Added `listWebhookDeliveries -> 200` - Added `listWebhookDeliveries -> 401` - Added `listWebhookDeliveries -> 403` - Added `listWebhookDeliveries -> 429` - Added `listPaymentReasons -> 200` - Added `listPaymentReasons -> 401` - Added `listPaymentReasons -> 403` - Added `listPaymentReasons -> 429` - Added `getPolicy -> 200` - Added `getPolicy -> 401` - Added `getPolicy -> 403` - Added `getPolicy -> 429` - Added `getIndicativeQuote -> 403` - Added `listBeneficiaries -> 403` - Added `createBeneficiary -> 401` - Added `createBeneficiary -> 403` - Added `createBeneficiary -> 503` - Added `addBeneficiaryMethod -> 401` - Added `addBeneficiaryMethod -> 403` - Added `addBeneficiaryMethod -> 503` - Added `getBeneficiaryByExternalId -> 200` - Added `getBeneficiaryByExternalId -> 401` - Added `getBeneficiaryByExternalId -> 403` - Added `getBeneficiaryByExternalId -> 404` - Added `getBeneficiaryByExternalId -> 429` - Added `getBeneficiary -> 200` - Added `getBeneficiary -> 401` - Added `getBeneficiary -> 403` - Added `getBeneficiary -> 404` - Added `getBeneficiary -> 429` - Added `updateBeneficiary -> 200` - Added `updateBeneficiary -> 400` - Added `updateBeneficiary -> 401` - Added `updateBeneficiary -> 403` - Added `updateBeneficiary -> 404` - Added `updateBeneficiary -> 429` - Added `deleteBeneficiary -> 200` - Added `deleteBeneficiary -> 401` - Added `deleteBeneficiary -> 403` - Added `deleteBeneficiary -> 404` - Added `deleteBeneficiary -> 429` - Added `deleteBeneficiaryMethod -> 200` - Added `deleteBeneficiaryMethod -> 401` - Added `deleteBeneficiaryMethod -> 403` - Added `deleteBeneficiaryMethod -> 404` - Added `deleteBeneficiaryMethod -> 429` - Added `getBeneficiaryMethodDetails -> 200` - Added `getBeneficiaryMethodDetails -> 401` - Added `getBeneficiaryMethodDetails -> 403` - Added `getBeneficiaryMethodDetails -> 404` - Added `getBeneficiaryMethodDetails -> 429` - Added `pricePayout -> 401` - Added `pricePayout -> 403` - Added `sendPayout -> 401` - Added `sendPayout -> 403` - Added `createPayout -> 202` - Added `createPayout -> 401` - Added `createPayout -> 403` - Added `createPayout -> 422` - Added `createPayoutBatch -> 202` - Added `createPayoutBatch -> 400` - Added `createPayoutBatch -> 401` - Added `createPayoutBatch -> 403` - Added `createPayoutBatch -> 409` - Added `createPayoutBatch -> 429` - Added `listPayoutBatches -> 200` - Added `listPayoutBatches -> 401` - Added `listPayoutBatches -> 403` - Added `listPayoutBatches -> 429` - Added `getPayoutBatch -> 200` - Added `getPayoutBatch -> 401` - Added `getPayoutBatch -> 403` - Added `getPayoutBatch -> 404` - Added `getPayoutBatch -> 429` - Added `listPayoutBatchItems -> 200` - Added `listPayoutBatchItems -> 401` - Added `listPayoutBatchItems -> 403` - Added `listPayoutBatchItems -> 404` - Added `listPayoutBatchItems -> 429` - Added `confirmPayoutBatch -> 200` - Added `confirmPayoutBatch -> 202` - Added `confirmPayoutBatch -> 401` - Added `confirmPayoutBatch -> 403` - Added `confirmPayoutBatch -> 404` - Added `confirmPayoutBatch -> 409` - Added `confirmPayoutBatch -> 429` - Added `cancelPayoutBatch -> 200` - Added `cancelPayoutBatch -> 401` - Added `cancelPayoutBatch -> 403` - Added `cancelPayoutBatch -> 404` - Added `cancelPayoutBatch -> 409` - Added `cancelPayoutBatch -> 429` - Added `listPayoutApprovals -> 200` - Added `listPayoutApprovals -> 400` - Added `listPayoutApprovals -> 401` - Added `listPayoutApprovals -> 403` - Added `listPayoutApprovals -> 429` - Added `getPayoutApproval -> 200` - Added `getPayoutApproval -> 401` - Added `getPayoutApproval -> 403` - Added `getPayoutApproval -> 404` - Added `getPayoutApproval -> 429` - Added `createPayoutLink -> 401` - Added `createPayoutLink -> 403` - Added `submitPayoutLink -> 403` - Added `submitPayoutLink -> 404` - Added `listBalanceTransactions -> 200` - Added `listBalanceTransactions -> 401` - Added `listBalanceTransactions -> 403` - Added `listBalanceTransactions -> 429` - Added `cancelPayout -> 401` - Added `cancelPayout -> 403` - Added `getPayoutFunding -> 401` - Added `getPayoutFunding -> 403` - Added `confirmPayoutFunding -> 401` - Added `confirmPayoutFunding -> 403` - Added `listEvents -> 401` - Added `listEvents -> 403` - Added `listAuditEvents -> 200` - Added `listAuditEvents -> 400` - Added `listAuditEvents -> 401` - Added `listAuditEvents -> 403` - Added `listAuditEvents -> 429` - Added `getBalance -> 401` - Added `getBalance -> 403` - Added `getBalanceHistory -> 401` - Added `getBalanceHistory -> 403` - Added `fundSandbox -> 401` - Added `fundSandbox -> 403` - Added `createSandboxWebhookEndpoint -> 401` - Added `createSandboxWebhookEndpoint -> 403` - Added `listSandboxWebhookDeliveries -> 401` - Added `listSandboxWebhookDeliveries -> 403` - Added `listPayouts -> 401` - Added `listPayouts -> 403` - Added `getPayout -> 401` - Added `getPayout -> 403` - Added `getFundingAccounts -> 401` - Added `getFundingAccounts -> 403` Schema fields: 116 added, 0 removed - Added `WalletBalance.currency` - Added `WalletBalance.network` - Added `WalletBalance.amount` - Added `LedgerBalance.currency` - Added `LedgerBalance.available` - Added `LedgerBalance.held` - Added `LedgerBalance.total` - Added `BalanceTransaction.id` - Added `BalanceTransaction.type` - Added `BalanceTransaction.amount` - Added `BalanceTransaction.fee` - Added `BalanceTransaction.net` - Added `BalanceTransaction.currency` - Added `BalanceTransaction.balanceAfter` - Added `BalanceTransaction.orderId` - Added `BalanceTransaction.snapshotId` - Added `BalanceTransaction.batchId` - Added `BalanceTransaction.reference` - Added `BalanceTransaction.endUserId` - Added `BalanceTransaction.reason` - Added `BalanceTransaction.description` - Added `BalanceTransaction.createdAt` - Added `Corridor.country` - Added `Corridor.limits` - Added `Corridor.settlement` - Added `Corridor.minimumSourceAmount` - Added `CreateBeneficiary.phone` - Added `CreatePayout.amount` - Added `CreatePayout.destinationAccountId` - Added `CreatePayout.amountLeg` - Added `CreatePayout.expectDestination` - Added `CreatePayout.maxDriftBps` - Added `CreatePayout.reference` - Added `CreatePayout.purposeOfPayment` - Added `CreatePayout.endUser` - Added `Payout.fee` - Added `Payout.expectedSettlementAt` - Added `PayoutBatch.batchId` - Added `PayoutBatch.externalReferenceId` - Added `PayoutBatch.status` - Added `PayoutBatch.autoCommit` - Added `PayoutBatch.counts` - Added `PayoutBatch.estimatedSourceTotal` - Added `PayoutBatch.error` - Added `PayoutBatch.createdAt` - Added `PayoutBatch.updatedAt` - Added `PayoutBatch.completedAt` - Added `PayoutBatchItem.index` - Added `PayoutBatchItem.status` - Added `PayoutBatchItem.instruction` - Added `PayoutBatchItem.instructionScrubbedAt` - Added `PayoutBatchItem.errors` - Added `PayoutBatchItem.payoutId` - Added `PayoutEvent.batchId` - Added `PayoutEvent.apiVersion` - Added `PayoutEvent.data` - Added `WebhookPayout.requiresFunding` - Added `WebhookEvent.id` - Added `WebhookEvent.sequence` - Added `WebhookEvent.createdAt` - Added `WebhookEvent.apiVersion` - Added `WebhookEvent.livemode` - Added `PayoutApproval.id` - Added `PayoutApproval.kind` - Added `PayoutApproval.status` - Added `PayoutApproval.requiredApprovals` - Added `PayoutApproval.approvals` - Added `PayoutApproval.payoutId` - Added `PayoutApproval.batchId` - Added `PayoutApproval.amount` - Added `PayoutApproval.currency` - Added `PayoutApproval.destinationAccountId` - Added `PayoutApproval.error` - Added `PayoutApproval.createdAt` - Added `PayoutApproval.expiresAt` - Added `PayoutApproval.updatedAt` - Added `PayoutApprovalEvent.approval` - Added `PayoutApprovalEvent.payoutId` - Added `WebhookEndpointDisabled.endpointId` - Added `WebhookEndpointDisabled.url` - Added `WebhookEndpointDisabled.reason` - Added `WebhookEndpointDisabled.consecutiveFailures` - Added `WebhookEndpointDisabled.lastSuccessAt` - Added `WebhookEndpointDisabled.disabledAt` - Added `PendingApproval.status` - Added `PendingApproval.approvalId` - Added `PendingApproval.approvalRequestId` - Added `PendingApproval.requiredApprovals` - Added `PendingApproval.expiresAt` - Added `AuditEvent.id` - Added `AuditEvent.action` - Added `AuditEvent.resourceType` - Added `AuditEvent.resourceId` - Added `AuditEvent.apiKeyPrefix` - Added `AuditEvent.actorUserId` - Added `AuditEvent.ip` - Added `AuditEvent.requestId` - Added `AuditEvent.outcome` - Added `AuditEvent.errorType` - Added `AuditEvent.createdAt` - Added `Policy.organizationId` - Added `Policy.mode` - Added `Policy.features` - Added `Policy.limits` - Added `Policy.approvals` - Added `Policy.purposeOfPayment` - Added `Policy.fees` - Added `Policy.rateLimits` - Added `Policy.idempotency` - Added `Policy.links` - Added `FundingAccount.id` - Added `FundingAccount.shape` - Added `FundingAccount.status` - Added `FundingAccount.settlesTo` - Added `FundingAccount.destination` - Added `FundingAccount.balance` Enum values: 162 added, 1 removed - Removed `schemas.PayoutFailureCode = canceled_by_platform` - Added `/organizations/{organizationId}/webhook-endpoints.get.responses.200.disabledReason = paused_by_owner` - Added `/organizations/{organizationId}/webhook-endpoints.get.responses.200.disabledReason = auto_disabled_after_failures` - Added `/organizations/{organizationId}/webhook-endpoints.get.responses.200.disabledReason = null` - Added `/recipients/{orgId}/{recipientId}.patch.type = individual` - Added `/recipients/{orgId}/{recipientId}.patch.type = business` - Added `/payments/organizations/{orgId}/quotes/offramp.post.amountLeg = source` - Added `/payments/organizations/{orgId}/quotes/offramp.post.amountLeg = destination` - Added `/payments/organizations/{orgId}/quotes/offramp.post.amountLeg = source_net` - Added `/payments/organizations/{orgId}/payouts/batches.get.parameters.1 = received` - Added `/payments/organizations/{orgId}/payouts/batches.get.parameters.1 = validating` - Added `/payments/organizations/{orgId}/payouts/batches.get.parameters.1 = awaiting_confirmation` - Added `/payments/organizations/{orgId}/payouts/batches.get.parameters.1 = creating` - Added `/payments/organizations/{orgId}/payouts/batches.get.parameters.1 = completed` - Added `/payments/organizations/{orgId}/payouts/batches.get.parameters.1 = canceled` - Added `/payments/organizations/{orgId}/payouts/batches.get.parameters.1 = failed` - Added `/payments/organizations/{orgId}/payouts/batches/{batchId}/items.get.parameters.2 = received` - Added `/payments/organizations/{orgId}/payouts/batches/{batchId}/items.get.parameters.2 = invalid` - Added `/payments/organizations/{orgId}/payouts/batches/{batchId}/items.get.parameters.2 = validated` - Added `/payments/organizations/{orgId}/payouts/batches/{batchId}/items.get.parameters.2 = creating` - Added `/payments/organizations/{orgId}/payouts/batches/{batchId}/items.get.parameters.2 = created` - Added `/payments/organizations/{orgId}/payouts/batches/{batchId}/items.get.parameters.2 = create_failed` - Added `/payments/organizations/{orgId}/payouts/batches/{batchId}/items.get.parameters.2 = canceled` - Added `/payments/organizations/{orgId}/payouts/batches/{batchId}/items.get.parameters.2 = requires_review` - Added `/payments/organizations/{orgId}/payouts/batches/{batchId}/items.get.parameters.5 = csv` - Added `/payout-links/{token}.get.responses.200.status = pending` - Added `/payout-links/{token}.get.responses.200.status = consuming` - Added `/payout-links/{token}.get.responses.200.status = failed` - Added `/payout-links/{token}/submit.post.oneOf.0.recipientType = individual` - Added `/payout-links/{token}/submit.post.oneOf.0.recipientType = business` - Added `/payout-links/{token}/submit.post.oneOf.1.recipientType = individual` - Added `/payout-links/{token}/submit.post.oneOf.1.recipientType = business` - Added `/payments/organizations/{orgId}/balance.get.responses.200.unavailable = network` - Added `/payments/organizations/{orgId}/balance.get.responses.200.unavailable = wallet` - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints.post.events = payout.pending` - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints.post.events = payout.processing` - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints.post.events = payout.completed` - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints.post.events = payout.failed` - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints.post.events = payout.returned` - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints.post.events = payout.canceled` - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints.post.events = payout_batch.awaiting_confirmation` - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints.post.events = payout_batch.completed` - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints.post.events = payout_batch.canceled` - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints.post.events = payout_batch.failed` - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints.post.events = checkout_payment.paid` - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints.post.events = checkout_payment.failed` - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints.post.events = checkout_payment.refunded` - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints.post.events = checkout_payment.reversed` - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints/{endpointId}/deliveries.get.responses.200.eventType = payout.pending` - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints/{endpointId}/deliveries.get.responses.200.eventType = payout.processing` - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints/{endpointId}/deliveries.get.responses.200.eventType = payout.completed` - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints/{endpointId}/deliveries.get.responses.200.eventType = payout.failed` - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints/{endpointId}/deliveries.get.responses.200.eventType = payout.returned` - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints/{endpointId}/deliveries.get.responses.200.eventType = payout.canceled` - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints/{endpointId}/deliveries.get.responses.200.eventType = payout_batch.awaiting_confirmation` - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints/{endpointId}/deliveries.get.responses.200.eventType = payout_batch.completed` - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints/{endpointId}/deliveries.get.responses.200.eventType = payout_batch.canceled` - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints/{endpointId}/deliveries.get.responses.200.eventType = payout_batch.failed` - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints/{endpointId}/deliveries.get.responses.200.eventType = payout_approval.pending` - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints/{endpointId}/deliveries.get.responses.200.eventType = payout_approval.approved` - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints/{endpointId}/deliveries.get.responses.200.eventType = payout_approval.rejected` - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints/{endpointId}/deliveries.get.responses.200.eventType = payout_approval.expired` - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints/{endpointId}/deliveries.get.responses.200.eventType = payout_approval.executed` - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints/{endpointId}/deliveries.get.responses.200.eventType = payout_approval.execution_failed` - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints/{endpointId}/deliveries.get.responses.200.eventType = webhook_endpoint.disabled` - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints/{endpointId}/deliveries.get.responses.200.eventType = checkout_payment.paid` - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints/{endpointId}/deliveries.get.responses.200.eventType = checkout_payment.failed` - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints/{endpointId}/deliveries.get.responses.200.eventType = checkout_payment.refunded` - Added `/payments/organizations/{orgId}/sandbox/webhook-endpoints/{endpointId}/deliveries.get.responses.200.eventType = checkout_payment.reversed` - Added `schemas.WalletBalance.currency = USDC` - Added `schemas.WalletBalance.currency = USDT` - Added `schemas.BalanceTransaction.type = funding` - Added `schemas.BalanceTransaction.type = payout` - Added `schemas.BalanceTransaction.type = payout_return` - Added `schemas.BalanceTransaction.type = hold` - Added `schemas.BalanceTransaction.type = hold_release` - Added `schemas.BalanceTransaction.type = adjustment` - Added `schemas.Corridor.fields.checksum = clabe` - Added `schemas.CreatePayout.amountLeg = source` - Added `schemas.CreatePayout.amountLeg = destination` - Added `schemas.CreatePayout.amountLeg = source_net` - Added `schemas.PayoutBatchStatus = received` - Added `schemas.PayoutBatchStatus = validating` - Added `schemas.PayoutBatchStatus = awaiting_confirmation` - Added `schemas.PayoutBatchStatus = creating` - Added `schemas.PayoutBatchStatus = completed` - Added `schemas.PayoutBatchStatus = canceled` - Added `schemas.PayoutBatchStatus = failed` - Added `schemas.PayoutBatchItemStatus = received` - Added `schemas.PayoutBatchItemStatus = invalid` - Added `schemas.PayoutBatchItemStatus = validated` - Added `schemas.PayoutBatchItemStatus = creating` - Added `schemas.PayoutBatchItemStatus = created` - Added `schemas.PayoutBatchItemStatus = create_failed` - Added `schemas.PayoutBatchItemStatus = canceled` - Added `schemas.PayoutBatchItemStatus = requires_review` - Added `schemas.PayoutEventType = payout.pending` - Added `schemas.PayoutEventType = payout.processing` - Added `schemas.PayoutEventType = payout.completed` - Added `schemas.PayoutEventType = payout.failed` - Added `schemas.PayoutEventType = payout.returned` - Added `schemas.PayoutEventType = payout.canceled` - Added `schemas.PayoutEventType = payout_batch.awaiting_confirmation` - Added `schemas.PayoutEventType = payout_batch.completed` - Added `schemas.PayoutEventType = payout_batch.canceled` - Added `schemas.PayoutEventType = payout_batch.failed` - Added `schemas.PayoutEventType = payout_approval.pending` - Added `schemas.PayoutEventType = payout_approval.approved` - Added `schemas.PayoutEventType = payout_approval.rejected` - Added `schemas.PayoutEventType = payout_approval.expired` - Added `schemas.PayoutEventType = payout_approval.executed` - Added `schemas.PayoutEventType = payout_approval.execution_failed` - Added `schemas.PayoutEventType = webhook_endpoint.disabled` - Added `schemas.PayoutEventType = checkout_payment.paid` - Added `schemas.PayoutEventType = checkout_payment.failed` - Added `schemas.PayoutEventType = checkout_payment.refunded` - Added `schemas.PayoutEventType = checkout_payment.reversed` - Added `schemas.PayoutApprovalStatus = pending` - Added `schemas.PayoutApprovalStatus = approved` - Added `schemas.PayoutApprovalStatus = rejected` - Added `schemas.PayoutApprovalStatus = expired` - Added `schemas.PayoutApprovalStatus = executing` - Added `schemas.PayoutApprovalStatus = executed` - Added `schemas.PayoutApprovalStatus = execution_failed` - Added `schemas.PayoutApprovalStatus = execution_unknown` - Added `schemas.PayoutApproval.kind = payout` - Added `schemas.PayoutApproval.kind = payout_batch` - Added `schemas.AuditEvent.outcome = ok` - Added `schemas.AuditEvent.outcome = error` - Added `schemas.PaymentReason = charitable_contributions` - Added `schemas.PaymentReason = education_fees` - Added `schemas.PaymentReason = employee_salaries_or_wages` - Added `schemas.PaymentReason = gifts` - Added `schemas.PaymentReason = investments` - Added `schemas.PaymentReason = purchase_of_goods` - Added `schemas.PaymentReason = purchase_of_services` - Added `schemas.PaymentReason = personal_transfers` - Added `schemas.PaymentReason = rent` - Added `schemas.PaymentReason = loans` - Added `schemas.PaymentReason = utility_bills` - Added `schemas.PaymentReason = family_support` - Added `schemas.PaymentReason = friends_support` - Added `schemas.PaymentReason = real_estate` - Added `schemas.PaymentReason = insurance` - Added `schemas.PaymentReason = intercompany_transfer` - Added `schemas.PaymentReason = taxes` - Added `schemas.PaymentReason = travel` - Added `schemas.Policy.mode = test` - Added `schemas.Policy.mode = live` - Added `schemas.Policy.approvals.appliesTo = payouts` - Added `schemas.Policy.approvals.appliesTo = batches` - Added `schemas.Policy.approvals.appliesTo = payout_links` - Added `x-webhooks.payout_batch.payload.type = payout_batch.awaiting_confirmation` - Added `x-webhooks.payout_batch.payload.type = payout_batch.completed` - Added `x-webhooks.payout_batch.payload.type = payout_batch.canceled` - Added `x-webhooks.payout_batch.payload.type = payout_batch.failed` - Added `x-webhooks.payout_approval.payload.type = payout_approval.pending` - Added `x-webhooks.payout_approval.payload.type = payout_approval.approved` - Added `x-webhooks.payout_approval.payload.type = payout_approval.rejected` - Added `x-webhooks.payout_approval.payload.type = payout_approval.expired` - Added `x-webhooks.payout_approval.payload.type = payout_approval.executed` - Added `x-webhooks.payout_approval.payload.type = payout_approval.execution_failed` - Added `x-webhooks.webhook_endpoint.payload.type = webhook_endpoint.disabled` ### 2026-08-18 Server URLs: - Removed `https://api.avvio.xyz/api/v1` - Added `https://api.avvio.xyz/business/api/v1` Documented responses: 23 added, 0 removed - Added `listCorridors -> 429` - Added `getIndicativeQuote -> 429` - Added `listBeneficiaries -> 429` - Added `createBeneficiary -> 429` - Added `addBeneficiaryMethod -> 429` - Added `pricePayout -> 429` - Added `sendPayout -> 429` - Added `createPayout -> 429` - Added `createPayoutLink -> 429` - Added `resolvePayoutLink -> 429` - Added `submitPayoutLink -> 429` - Added `getBalanceHistory -> 429` - Added `cancelPayout -> 429` - Added `getPayoutFunding -> 429` - Added `confirmPayoutFunding -> 429` - Added `listEvents -> 429` - Added `getBalance -> 429` - Added `fundSandbox -> 429` - Added `createSandboxWebhookEndpoint -> 429` - Added `listSandboxWebhookDeliveries -> 429` - Added `listPayouts -> 429` - Added `getPayout -> 429` - Added `getFundingAccounts -> 429` ### 2026-08-16 The first published version of this contract. ## Checkout API The version a client pins is `info.version` in [partner-checkout.openapi.yaml](/partner-checkout.openapi.yaml). Newest first. ### 2026-09-28.2 Documented responses: - Removed `refundCheckoutPayment -> 502` - Added `createCheckoutLink -> 404` - Added `createCheckoutLink -> 500` - Added `updateCheckoutLink -> 409` - Added `deleteCheckoutLink -> 409` - Added `publishCheckoutLink -> 500` - Added `pauseCheckoutLink -> 409` - Added `refundCheckoutPayment -> 500` Schema fields: - Added `Error.originalBatchId` - Added `Error.originalRequestId` - Added `Error.existingRecipientId` - Added `Error.existingMethodId` - Added `CheckoutLineItem.id` Enum values: 22 added, 1 removed - Removed `parameters.AllowDuplicate = true` - Added `schemas.CheckoutMethodInput.currency = USD` - Added `schemas.CheckoutMethodInput.currency = EUR` - Added `schemas.CheckoutMethodInput.currency = GBP` - Added `schemas.CheckoutMethodInput.currency = AED` - Added `schemas.CheckoutMethodInput.currency = MXN` - Added `schemas.CheckoutMethodInput.currency = BRL` - Added `schemas.CheckoutMethodInput.currency = ARS` - Added `schemas.CheckoutMethodInput.currency = INR` - Added `schemas.CheckoutMethodInput.currency = CNY` - Added `schemas.CheckoutMethodInput.currency = HKD` - Added `schemas.CheckoutMethodInput.currency = PHP` - Added `schemas.CheckoutMethodInput.currency = SGD` - Added `schemas.CheckoutMethodInput.currency = IDR` - Added `schemas.CheckoutMethodInput.currency = THB` - Added `schemas.CreateCheckoutLinkRequest.currency = IDR` - Added `schemas.CreateCheckoutLinkRequest.currency = THB` - Added `schemas.UpdateCheckoutLinkRequest.currency = IDR` - Added `schemas.UpdateCheckoutLinkRequest.currency = THB` - Added `schemas.CreateCheckoutProductRequest.currency = IDR` - Added `schemas.CreateCheckoutProductRequest.currency = THB` - Added `schemas.UpdateCheckoutProductRequest.currency = IDR` - Added `schemas.UpdateCheckoutProductRequest.currency = THB` ### 2026-09-28.1 No operation, response, field or enum changed; descriptions and examples only. ### 2026-09-21.1 Operations: - Added `POST /checkout/organizations/{orgId}/links/{linkId}/payments/simulate (simulateCheckoutPayment)` - Added `POST /checkout/organizations/{orgId}/payments/{paymentId}/refund (refundCheckoutPayment)` - Added `POST /checkout/organizations/{orgId}/payments/{paymentId}/simulate (simulateCheckoutPaymentOutcome)` - Added `GET /checkout/organizations/{orgId}/sandbox/scenarios (listCheckoutSandboxScenarios)` Documented responses: 27 added, 0 removed - Added `simulateCheckoutPayment -> 200` - Added `simulateCheckoutPayment -> 400` - Added `simulateCheckoutPayment -> 401` - Added `simulateCheckoutPayment -> 403` - Added `simulateCheckoutPayment -> 404` - Added `simulateCheckoutPayment -> 409` - Added `simulateCheckoutPayment -> 429` - Added `refundCheckoutPayment -> 200` - Added `refundCheckoutPayment -> 400` - Added `refundCheckoutPayment -> 401` - Added `refundCheckoutPayment -> 403` - Added `refundCheckoutPayment -> 404` - Added `refundCheckoutPayment -> 409` - Added `refundCheckoutPayment -> 429` - Added `refundCheckoutPayment -> 502` - Added `simulateCheckoutPaymentOutcome -> 200` - Added `simulateCheckoutPaymentOutcome -> 400` - Added `simulateCheckoutPaymentOutcome -> 401` - Added `simulateCheckoutPaymentOutcome -> 403` - Added `simulateCheckoutPaymentOutcome -> 404` - Added `simulateCheckoutPaymentOutcome -> 409` - Added `simulateCheckoutPaymentOutcome -> 429` - Added `listCheckoutSandboxScenarios -> 200` - Added `listCheckoutSandboxScenarios -> 400` - Added `listCheckoutSandboxScenarios -> 401` - Added `listCheckoutSandboxScenarios -> 403` - Added `listCheckoutSandboxScenarios -> 429` Schema fields: 16 added, 0 removed - Added `CheckoutPayment.refunds` - Added `RefundCheckoutPaymentRequest.amount` - Added `RefundCheckoutPaymentRequest.reason` - Added `RefundCheckoutPaymentRequest.note` - Added `CheckoutRefund.id` - Added `CheckoutRefund.paymentId` - Added `CheckoutRefund.amountBase` - Added `CheckoutRefund.currency` - Added `CheckoutRefund.decimals` - Added `CheckoutRefund.reason` - Added `CheckoutRefund.note` - Added `CheckoutRefund.source` - Added `CheckoutRefund.status` - Added `CheckoutRefund.actor` - Added `CheckoutRefund.createdAt` - Added `WebhookCheckoutPayment.refund` Enum values: 18 added, 0 removed - Added `/checkout/organizations/{orgId}/payments/{paymentId}/simulate.post.action = refund` - Added `/checkout/organizations/{orgId}/payments/{paymentId}/simulate.post.action = chargeback` - Added `/checkout/organizations/{orgId}/payments/{paymentId}/simulate.post.action = fail` - Added `parameters.AllowDuplicate = true` - Added `schemas.RefundReason = requested_by_customer` - Added `schemas.RefundReason = duplicate` - Added `schemas.RefundReason = fraudulent` - Added `schemas.RefundReason = other` - Added `schemas.CheckoutRefund.source = dashboard` - Added `schemas.CheckoutRefund.source = api` - Added `schemas.CheckoutRefund.source = acquirer` - Added `schemas.CheckoutRefund.status = pending` - Added `schemas.CheckoutRefund.status = succeeded` - Added `schemas.WebhookCheckoutPayment.refund.source = dashboard` - Added `schemas.WebhookCheckoutPayment.refund.source = api` - Added `schemas.WebhookCheckoutPayment.refund.source = acquirer` - Added `schemas.CheckoutWebhookEvent.type = checkout_payment.partially_refunded` - Added `x-webhooks.checkout_payment.payload.type = checkout_payment.partially_refunded` ### 2026-09-13.1 The first published version of this contract. ## @avvio/payments (SDK, CLI and MCP server) ### Unreleased - `beneficiary create` no longer requires `--email`, and `createBeneficiary()` types `email` as optional. The API always accepted a beneficiary without one; the address is a contact detail and plays no part in routing the payout. ### 0.8.1 - **`createPayoutLink()` forwards `endUser`.** `{ name, email }` for the sender was accepted by the API but dropped by the client, so the Reg E receipt had nowhere to go unless the recipient page asked for an email. For the in-app flow, see `@avvio/payouts-react-native`. ### 0.8.0 - **The MCP server guides the agent.** On connect it now sends instructions: the order of calls to pay someone, the rules that prevent double-paying or losing a payout, and the sandbox test accounts. Two prompts are listed for the host's menu: `integrate_payouts` (build the integration into a codebase, given `stack` and `use_case`) and `sandbox_walkthrough` (one test payout, paid then returned, narrated). `list_payouts` takes `reference`, `status`, `endUserId`, `limit` and `cursor`, so an agent can check whether a send whose response was lost actually went out before it retries. - **Refunds over the API.** `refundCheckoutPayment(paymentId, { amount?, reason?, note? })` (`POST /checkout/organizations/{orgId}/payments/{paymentId}/refund`), whole or in part, with Stripe's four `reason` values. **The key needs the new `refunds` scope**, a consent only an owner or admin can grant when issuing a key (`scopes: ["write", "refunds"]`); keys without it, including keys issued before scopes existed, get `403 INSUFFICIENT_SCOPE`. CLI `checkout refund --full | --amount 12.50`; MCP `refund_checkout_payment` (confirm-gated, requires an idempotency key). `Idempotency-Key` is required and is what makes a retry safe: the acquirer's refund endpoint has none of its own. New error types `REFUND_NOT_ALLOWED`, `REFUND_DISPUTED`, `REFUND_EXCEEDS_REMAINING`, `REFUND_IN_PROGRESS`, `REFUND_OUTCOME_UNKNOWN`. - **`checkout_payment.partially_refunded`**, a new opt-in event: part of a payment went back and the status stays `paid`. Both refund events carry the refund just made in `refund` (`id`, `amount`, `reason`, `note`, `source`, `at`); `refunded` stays the cumulative figure. Additive, and a receiver that returns `2xx` for unknown types is unaffected. The former "a partial refund fires no event" silence is gone. - **`refunds` on every payment read**: each refund with who asked for it (`source`: `dashboard` | `api` | `acquirer`), why, and when. Refunds made at the card processor's own tools appear here too, as the acquirer's. - **Checkout has a sandbox.** A test key now works on every checkout route, which supersedes the "live keys only" note under 0.6.0 below. Your sandbox organization is provisioned already verified and already able to sell by card, so a test key publishes a card link on its first call. `simulateCheckoutPayment(linkId)` pays it, and **the link's amount picks the outcome**: the last two digits of the total in minor units select paid, declined, slow settlement, refunded, partially refunded, or CHARGED BACK. `listCheckoutSandboxScenarios()` returns the table; `simulateCheckoutPaymentOutcome(paymentId, action)` forces one immediately rather than waiting out the timeline. CLI `checkout simulate` and `checkout scenarios`. No MCP tools: an agent that can manufacture "you were paid" is a worse idea than one that can top up a fake balance. - The acceptor is SIMULATED rather than a card processor's own sandbox, because a chargeback — `checkout_payment.reversed`, money taken back after you booked it — cannot be triggered in one. Nothing is charged, no card is involved, and events are signed and delivered exactly as live ones are, carrying `livemode: false`. What it does not simulate: 3-D Secure, the express wallet buttons, and real per-card decline codes. - **`TEST_MODE_UNSUPPORTED` is no longer thrown**, and is gone from the error union and from `ERRORS.md`, which that union is derived from. An existing `case 'TEST_MODE_UNSUPPORTED':` still compiles — the union admits any string so that a partner on an old package can build against a newer API — and the branch is now dead. `LIVE_MODE_UNSUPPORTED` means the opposite: a LIVE key on a sandbox-only route. ### 0.7.0 - **Checkout links can expire.** `expiresAt` (ISO-8601 with a timezone, in the future, at most a year out) on `createCheckoutLink()`; past it the page answers `410` and the link's `status` reads `expired`, a new terminal value beside `cancelled`. Every link read carries `expiresAt`. Publishing a draft whose deadline has passed is `400 LINK_EXPIRED` (as `publishError.type` inside a `publish: true` create). CLI `checkout create --expires-in 30m|2h|7d`; MCP `create_checkout_link` takes `expiresAt`; `list_checkout_links` and `listCheckoutLinks()` accept `status: 'expired'`. - **`updateCheckoutLink()`** (`PATCH /checkout/organizations/{orgId}/links/{linkId}`, CLI `checkout update`, MCP `update_checkout_link`). Drafts take any create field; a LIVE link takes `expiresAt` on its own (an instant, or `null` to clear it) and refuses anything else. - **`source` on every link** (`api` | `dashboard`) and a matching `listCheckoutLinks({ source })` filter (CLI `--source`, MCP `list_checkout_links.source`). A server integration mints one link per order; the dashboard now lists those apart from links made by hand. - **`linkExpiredAt` on `CheckoutPaymentEvent`**: the link's deadline when the payment landed after it, else null. Additive; a receiver that ignores it is unaffected. - `Idempotency-Key` is now enforced as required on every checkout write, including product update and delete, link update, pause and delete, which had accepted a partner call without one. The client has always minted a key, so nothing changes for SDK users. ### 0.6.0 - **Checkout: accept payments on your website.** Money ARRIVING, on the same key, webhook endpoint and event feed as payouts. `createCheckoutLink()` (`POST /checkout/organizations/{orgId}/links`; `publish: true` returns `shareUrl` in one call, the way Stripe's Checkout returns `url`), `getCheckoutLink()`, `listCheckoutLinks()`, `pauseCheckoutLink()` (permanent in this version), `listCheckoutPayments()`, and a catalog: `createProduct()`, `listProducts()`. Stripe-shaped fields: `successUrl`, `cancelUrl`, `clientReferenceId`, `metadata`. CLI `checkout` and `product`; MCP `create_checkout_link`, `get_checkout_link`, `list_checkout_links`, `pause_checkout_link` (confirm-gated), `list_checkout_payments`, `create_product`, `list_products`. - **Four new webhook events**, `checkout_payment.paid`, `.failed`, `.refunded`, `.reversed`, on the same signing and retry ladder. **Opt-in:** an endpoint with an empty `events` list does not receive them; name the types. `data` is `CheckoutPaymentEvent`, decimal strings like `WebhookPayout`. - **Live keys only.** A test key gets `400 TEST_MODE_UNSUPPORTED` on every checkout route; checkout has no sandbox yet. *(Superseded — see Unreleased above. Kept as the record of what 0.6.0 actually shipped.)* - `Idempotency-Key` is required from an API key on every checkout write; the client mints one when you do not pass it, as it does for payouts. - A refused `publish: true` does not throw: `createCheckoutLink()` resolves with the kept draft and `publishError`. Refunds are dashboard-only. Everything below shipped in the same release; the removal was agreed before any partner integrated: `balanceHistory()` is gone from the SDK (the `GET /balance/history` endpoint itself remains). `listBalanceTransactions()` is the SDK's one money feed. Everything else is additive. - **`getPolicy()`** (`GET .../policy`, CLI `policy`, MCP `get_policy`): what your organization is bound by, read live: payout caps, the approval threshold and M, effective features, rate limits per minute, idempotency windows and the currencies that need a `purposeOfPayment`. Read it before the first send instead of learning a cap from a `422` or an approval from a `202`. - **`balanceHistory()` removed** (and the CLI's `balance --history`); the `GET /balance/history` endpoint is not. Same rows, one feed: `listBalanceTransactions()` / `eachBalanceTransaction()`, newest first, `id` as the cursor, holds and fees included. - **`purposeOfPayment` is required for INR, GHS, CNY and BRL payouts** (`400 VALIDATION_ERROR` naming the field, before anything is priced). Validated against the corridor catalogue whenever sent; never defaulted on your behalf. - **`balance()` always carries `ledger`** (per currency: `available`, `held`, `total`, from our own record) beside the payment network's figure. The two are never summed. - **`balance()` counts your wallet.** `amount` and `balances` are now everything a payout can draw on: what the payment network holds for you (`provider`, new) plus the USD stablecoins in your own wallet (`wallet`, new, per chain, USDC and USDT at face value). A wallet-funded routing holds none of your money at the network, so an organization with $3,000 of USDC in its wallet used to read `0.00`. `ledger` is unchanged and describes the `provider` part only. - **Every mutation carries an `Idempotency-Key`.** The API now honours the header on every `POST`, `PATCH` and `DELETE`, so the client mints one per call for the methods that did not already (`updateBeneficiary`, `deleteBeneficiary`, `deleteBeneficiaryMethod`, `quote`, `pricePayout`, `cancelPayout`) and each accepts `{ idempotencyKey }` to supply your own. Retries reuse that key, never a fresh one per attempt; a mutation is still only ever retried under the key it first went out with. The one exception is `createWebhookEndpoint()`, which sends no key and is not retried: the server ignores the header on routes that return a secret once, because a stored replay would keep it for seven days. - **`fee` on the payout.** `payout()`, `getPayout()` and `listPayouts()` rows carry `fee` (`Money | null`), the same value the event `data` and the `payout` row on `listBalanceTransactions()` already reported. It is inside `sourceAmount`, not on top of it. - **The feed row is the webhook body.** `listEvents()` rows carry `data` — the same object a webhook delivers for the same event, with amounts, `fee`, `rate`, `reference` and `endUserId` — plus `apiVersion` and `batchId`. Batch, approval and endpoint events now appear in the feed (`payoutId` is `null` on them); `type` (string or array) narrows it. Rows become readable about two seconds after they happen. - **Webhook envelope.** Deliveries carry `{ id, sequence, type, createdAt, apiVersion, livemode, data }`; `id` equals `svix-id` and the feed row's `id`. New header `Avvio-Webhook-Version`. Retries now run nine rungs over roughly 70 hours with jitter; endpoints that stay dead are auto-disabled and `webhookEndpoints()` carries `disabledReason`, `consecutiveFailures`, `lastSuccessAt`, `lastFailureAt`. - **Approvals.** `payout()` and `confirmPayoutBatch()` may answer 202 with a `PendingApproval` when the organization requires human approval; `listApprovals()` / `getApproval()` read the queue (also `approvals` / `approval` on the CLI and `list_approvals` / `get_approval` MCP tools). Approve and reject are deliberately absent: a key cannot. - **Audit trail.** `listAuditEvents()` and `eachAuditEvent()` page who did what with which credential, newest first (`audit-events` on the CLI, `list_audit_events` MCP tool). - New error types `PAYOUT_LIMIT_EXCEEDED` (422) and `PAYOUT_REFUSED` (422) on `payout()`; `PAYOUT_BATCH_AWAITING_APPROVAL` (409) on `confirmPayoutBatch()`; `USE_POST_PAYOUTS` (403) on `pricePayout()`, `acceptQuote()` and payout links when the organization has an approval threshold or a velocity cap. - **Balance transactions.** `listBalanceTransactions()` pages every change to what you can spend, newest first, each row with `balanceAfter`: funding, payouts, returns, holds and their release, operator adjustments. `id` is the cursor and the dedupe key, so a reconciler can check its ledger row by row instead of against one number. `eachBalanceTransaction()` pages for you. Also a CLI command (`balance-transactions`) and a read-only MCP tool (`list_balance_transactions`). - `balance()` may now carry `balances` (per currency, from the payment network). - `listBalanceTransactions()` is served on every environment; an empty page means no rows yet. (`LEDGER_NOT_AVAILABLE`, briefly documented in a pre-release draft, was never shipped.) - `PAYOUT_UNDER_REVIEW` is removed from the error type union; the review state it described cannot occur. `PAYOUT_REFUSED` stays. --- ### 0.5.0 Additive. Nothing that worked at 0.4.0 changes. - **Mass payouts.** `createPayoutBatch()` submits up to 1,000 payout instructions as one run — each line exactly a `POST /payouts` body — with the idempotency key covering the RUN, so a resubmitted file is the same batch, never a second payroll. The batch validates every line before anything is priced or debited; `autoCommit: true` (the default) sends a clean run straight to creation, and any validation errors hold it at `awaiting_confirmation` for `confirmPayoutBatch()` or `cancelPayoutBatch()`. `externalReferenceId` (your run id) is required and unique per organization; a repeat under a fresh key is `PAYOUT_BATCH_DUPLICATE_REFERENCE` naming the original batch. Batch submission is gated per organization (`MASS_PAYOUTS_DISABLED`) and limited to 30 submits a minute. - `getPayoutBatch()`, `listPayoutBatches()` and `listPayoutBatchItems()` track a run. Items echo your instruction back verbatim, so errors join to your file by content; `?status=created` joins the run to the payout ledger, where each line lives the ordinary payout lifecycle. - `requires_review` is the one item status to read about before you need it: the outcome is unknown, it is never retried automatically, and support resolves it — re-running a line that may already have paid is how a crash becomes a double payment. - Four new webhook events — `payout_batch.awaiting_confirmation`, `payout_batch.completed`, `payout_batch.canceled`, `payout_batch.failed` — on the same signing and retry ladder as `payout.*`. There is deliberately no `payout_batch.creating`. - The batch methods are Node client surface only — deliberately not MCP tools, because one confirm committing up to 1,000 payments does not belong behind a single agent tool call, and not CLI commands yet: a file-shaped run wants a file-shaped input, which the CLI does not have a good spelling for. --- ### 0.4.0 The partner surface this release covers grew after the authentication change below; both land in the same unpublished version. New in the client, CLI and MCP server: - Read a beneficiary back by our id or by your own `externalId`, and fetch the full account behind one payment method — lists carry only `last4`, so the details are a deliberate second call rather than a field on every bulk read. - Correct a beneficiary's contact details, and delete a beneficiary or one of its payment methods. The registered account is not editable: the rail validated it, so a wrong account is a new method, not an edit. - `paymentReason` values, read from the API rather than guessed. - List your webhook endpoints and their recent delivery attempts, including what your server answered and when we will retry. Breaking authentication simplification: - The complete `avvio_live_*` or `avvio_test_*` API key is the only request credential. The client, CLI, and MCP server no longer require `AVVIO_PRIVATE_KEY` or add request-signing headers. - Historical public `akid_*` signing identifiers and retired `ak_live_*` / `ak_test_*` credentials are rejected locally rather than being treated as bearer secrets. - Test keys work in ReadMe's API explorer, including the operation that creates a hosted payout link. Live keys remain server-side only. --- ### 0.3.0 Breaking authentication hardening: - The client, CLI, and MCP server now accept only signed `akid_live_*` and `akid_test_*` identifiers. - `AVVIO_PRIVATE_KEY` (or `privateKeyPem`) is required for every accepted API credential. Retired `ak_live_*` and `ak_test_*` bearer credentials fail at client construction instead of reaching the network. ### 0.2.0 Additive. Nothing that worked at 0.1.0 changes. - **Send someone a figure named in YOUR currency, fees on top.** `payout({amountLeg: 'source_net'})` reads `amount` as what the recipient is to receive, converted at the market rate `quote()` publishes, with the fees added to your debit. "Send them $200 worth." On a live corridor, 200 USD paid out 3426.81 MXN and debited 203.447236 — the fees, plus the difference between the market rate quoted and the rate the network executed at. `--worth` on the CLI. - **Pay an exact amount, with the fees on top.** `payout({amountLeg: 'destination'})` makes `amount` the figure the beneficiary RECEIVES, in their currency, and the fees are added to your debit instead of taken out of it. On a live corridor, naming 3400 MXN debited 201.879397 USDC and paid out 3400.00. `--exact` on the CLI, `amountLeg` on the `send_payout` MCP tool. Available where `capabilities.exactOutput` is true on the corridors call; refused with `EXACT_OUTPUT_UNSUPPORTED` elsewhere, rather than quietly pricing the other side. - **`quote()` now answers on every routing.** It previously refused with `INDICATIVE_PRICING_UNAVAILABLE` for some organizations, on the endpoint the quickstart calls step 3. - `limits` is omitted from a quote when the routing publishes no corridor floor or ceiling, instead of being reported as `{min: "0", max: "0"}` — a zero minimum reads as a promise that any amount is sendable. - `endUser.id`, still optional, is now indexed: "everything I have paid this person" is a fast lookup rather than a scan. ### 0.1.0 First release. - Node client, CLI, and MCP server, sharing one core. Zero dependencies. - Sandbox with deterministic outcomes chosen by the last four digits of the beneficiary's account number, including `0003`, which completes and is then returned by the bank. - `payout()` and `POST /payouts` price and send in one call, refusing to send when the quote has drifted from what you promised the payer. - Idempotency on every mutation, generated for you if you do not supply one. - Webhook verification built in — no third-party library needed. ### Known limits at 0.1.0 Stated here rather than discovered by you: - **Cancellation does not exist.** `canceled` is in the status vocabulary because we expect to need it; there is no endpoint today. - **Exact-output depends on your routing.** Check `capabilities.exactOutput` on the corridors call before offering it in your UI. - **`GET /payouts` filters** are available; a cursor is returned but the aggregate page size is capped. - **Sandbox rates are fixed** and settlement takes seconds, not days.