Skip to content
Avvio Docs
Dashboard

Resources

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 has the versioning and deprecation policy.

Payouts API

Section titled “Payouts API”

The version a client pins is info.version in partner-payouts.openapi.yaml. Newest first.

2026-09-30.1 (unreleased)

Section titled “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

Section titled “2026-09-28.2”

Documented responses:

  • Added getBalanceHistory -> 400
  • Added getBalanceHistory -> 413

2026-09-28.1

Section titled “2026-09-28.1”

Documented responses:

  • Added createBeneficiary -> 422

2026-09-25.2

Section titled “2026-09-25.2”

No operation, response, field or enum changed; descriptions and examples only.

2026-09-25.1

Section titled “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

Section titled “2026-09-22.1”

No operation, response, field or enum changed; descriptions and examples only.

2026-09-21.1

Section titled “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

Section titled “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

Section titled “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

Section titled “2026-08-16”

The first published version of this contract.

Checkout API

Section titled “Checkout API”

The version a client pins is info.version in partner-checkout.openapi.yaml. Newest first.

2026-09-28.2

Section titled “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

Section titled “2026-09-28.1”

No operation, response, field or enum changed; descriptions and examples only.

2026-09-21.1

Section titled “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

Section titled “2026-09-13.1”

The first published version of this contract.

@avvio/payments (SDK, CLI and MCP server)

Section titled “@avvio/payments (SDK, CLI and MCP server)”

Unreleased

Section titled “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

Section titled “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

Section titled “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 <paymentId> --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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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.

Was this page helpful?