feat: refund PB→merchant payments

README.md

@@ -37,6 +37,7 @@ PostgreSQL (account metadata)  +  TigerBeetle (ledger / balances)
 | `POST` | `/accounts/{id}/payments` | Pay a merchant (MCC-validated, others-first splitting) |
 | `POST` | `/accounts/{id}/withdrawals` | Withdraw from self-pool only |
 | `POST` | `/normal-accounts/{id}/transfers/{id}/reverse` | Reverse a posted transfer (admin) |
+| `POST` | `/pb-accounts/{id}/payments/{id}/refund` | Refund a settled PB payment in whole or in part; multiple partials allowed (admin) |
 
 The API is defined using [Smithy](https://smithy.io/) models under `model/`. A generated Rust client SDK lives at `crates/pba_client/`.
 

WHAT.md

@@ -60,3 +60,30 @@ Constraints:
 - After reversal, the funds sit in the source normal account. The admin can
   separately call `WithdrawFromNormalAccount` to return them to the sponsor's
   bank.
+
+## Refunding a PB → merchant payment
+
+Settled PB payments can be refunded by an admin in whole or in part. Each
+refund is recorded as a new compensating transaction (1 or 2 rows
+mirroring the payment's pool split) plus matching TigerBeetle transfers
+in the opposite direction (debit the merchant settlement sentinel, credit
+the PB pool). Original payment rows are never mutated; each refund row
+links back via `reverses_transaction_id`.
+
+- Multiple partial refunds are allowed per payment; the sum must not
+  exceed the original payment amount.
+- Refund credits self-pool first up to that pool's remaining-unrefunded
+  amount, then others-pool. This restores the holder's self-pool
+  flexibility first.
+- The PB account must be Active to accept a refund. Refund rows
+  themselves cannot be refunded.
+- Refunds are admin-only via
+  `POST /pb-accounts/{id}/payments/{id}/refund` and via the Refund
+  button on the admin transaction-detail page.
+
+The MCC is not re-validated on refund — the original payment already
+passed MCC validation, and a refund restores state rather than
+authorising new spend. The merchant settlement sentinel has no balance
+constraint at TigerBeetle, so refunds never fail with `InsufficientFunds`;
+over-amount cases are caught with `RefundAmountInvalid` before TigerBeetle
+is touched.

crates/pba_client/src/client.rs

@@ -181,6 +181,8 @@ mod post_normal_account_transfer;
 
 mod post_pb_account_deposit;
 
+mod refund_pb_account_payment;
+
 mod reverse_normal_account_transfer;
 
 mod transfer_to_pb_account;

crates/pba_client/src/client/customize.rs

@@ -34,6 +34,7 @@
 
 
 
+
 
 
 /// `CustomizableOperation` allows for configuring a single operation invocation before it is sent.

crates/pba_client/src/client/refund_pb_account_payment.rs

@@ -0,0 +1,29 @@
+// Code generated by software.amazon.smithy.rust.codegen.smithy-rs. DO NOT EDIT.
+impl super::Client {
+    /// Constructs a fluent builder for the [`RefundPBAccountPayment`](crate::operation::refund_pb_account_payment::builders::RefundPBAccountPaymentFluentBuilder) operation.
+                            ///
+                            /// - The fluent builder is configurable:
+    ///   - [`account_id(impl Into<String>)`](crate::operation::refund_pb_account_payment::builders::RefundPBAccountPaymentFluentBuilder::account_id) / [`set_account_id(Option<String>)`](crate::operation::refund_pb_account_payment::builders::RefundPBAccountPaymentFluentBuilder::set_account_id):<br>required: **true**<br>(undocumented)<br>
+    ///   - [`payment_id(impl Into<String>)`](crate::operation::refund_pb_account_payment::builders::RefundPBAccountPaymentFluentBuilder::payment_id) / [`set_payment_id(Option<String>)`](crate::operation::refund_pb_account_payment::builders::RefundPBAccountPaymentFluentBuilder::set_payment_id):<br>required: **true**<br>(undocumented)<br>
+    ///   - [`amount(i64)`](crate::operation::refund_pb_account_payment::builders::RefundPBAccountPaymentFluentBuilder::amount) / [`set_amount(Option<i64>)`](crate::operation::refund_pb_account_payment::builders::RefundPBAccountPaymentFluentBuilder::set_amount):<br>required: **true**<br>Monetary amount in the smallest currency unit (e.g., paise for INR).<br>
+    ///   - [`description(impl Into<String>)`](crate::operation::refund_pb_account_payment::builders::RefundPBAccountPaymentFluentBuilder::description) / [`set_description(Option<String>)`](crate::operation::refund_pb_account_payment::builders::RefundPBAccountPaymentFluentBuilder::set_description):<br>required: **false**<br>(undocumented)<br>
+    ///   - [`gateway_ref(impl Into<String>)`](crate::operation::refund_pb_account_payment::builders::RefundPBAccountPaymentFluentBuilder::gateway_ref) / [`set_gateway_ref(Option<String>)`](crate::operation::refund_pb_account_payment::builders::RefundPBAccountPaymentFluentBuilder::set_gateway_ref):<br>required: **false**<br>(undocumented)<br>
+    ///   - [`idempotency_key(impl Into<String>)`](crate::operation::refund_pb_account_payment::builders::RefundPBAccountPaymentFluentBuilder::idempotency_key) / [`set_idempotency_key(Option<String>)`](crate::operation::refund_pb_account_payment::builders::RefundPBAccountPaymentFluentBuilder::set_idempotency_key):<br>required: **false**<br>(undocumented)<br>
+                            /// - On success, responds with [`RefundPbAccountPaymentOutput`](crate::operation::refund_pb_account_payment::RefundPbAccountPaymentOutput) with field(s):
+    ///   - [`refund_id(String)`](crate::operation::refund_pb_account_payment::RefundPbAccountPaymentOutput::refund_id): (undocumented)
+    ///   - [`original_payment_id(String)`](crate::operation::refund_pb_account_payment::RefundPbAccountPaymentOutput::original_payment_id): (undocumented)
+    ///   - [`account_id(String)`](crate::operation::refund_pb_account_payment::RefundPbAccountPaymentOutput::account_id): (undocumented)
+    ///   - [`amount(i64)`](crate::operation::refund_pb_account_payment::RefundPbAccountPaymentOutput::amount): Monetary amount in the smallest currency unit (e.g., paise for INR).
+    ///   - [`amount_to_self(i64)`](crate::operation::refund_pb_account_payment::RefundPbAccountPaymentOutput::amount_to_self): Monetary amount in the smallest currency unit (e.g., paise for INR).
+    ///   - [`amount_to_others(i64)`](crate::operation::refund_pb_account_payment::RefundPbAccountPaymentOutput::amount_to_others): Monetary amount in the smallest currency unit (e.g., paise for INR).
+    ///   - [`original_amount(i64)`](crate::operation::refund_pb_account_payment::RefundPbAccountPaymentOutput::original_amount): Monetary amount in the smallest currency unit (e.g., paise for INR).
+    ///   - [`remaining_refundable(i64)`](crate::operation::refund_pb_account_payment::RefundPbAccountPaymentOutput::remaining_refundable): Monetary amount in the smallest currency unit (e.g., paise for INR).
+    ///   - [`status(String)`](crate::operation::refund_pb_account_payment::RefundPbAccountPaymentOutput::status): (undocumented)
+    ///   - [`correlation_id(String)`](crate::operation::refund_pb_account_payment::RefundPbAccountPaymentOutput::correlation_id): (undocumented)
+    ///   - [`created_at(DateTime)`](crate::operation::refund_pb_account_payment::RefundPbAccountPaymentOutput::created_at): ISO 8601 date-time.
+                            /// - On failure, responds with [`SdkError<RefundPBAccountPaymentError>`](crate::operation::refund_pb_account_payment::RefundPBAccountPaymentError)
+    pub fn refund_pb_account_payment(&self) -> crate::operation::refund_pb_account_payment::builders::RefundPBAccountPaymentFluentBuilder {
+                                crate::operation::refund_pb_account_payment::builders::RefundPBAccountPaymentFluentBuilder::new(self.handle.clone())
+                            }
+}
+

crates/pba_client/src/error_meta.rs

@@ -599,6 +599,27 @@ impl From<crate::operation::post_pb_account_deposit::PostPBAccountDepositError>
         }
     }
 }
+impl<R> From<::aws_smithy_runtime_api::client::result::SdkError<crate::operation::refund_pb_account_payment::RefundPBAccountPaymentError, R>> for Error where R: Send + Sync + std::fmt::Debug + 'static {
+    fn from(err: ::aws_smithy_runtime_api::client::result::SdkError<crate::operation::refund_pb_account_payment::RefundPBAccountPaymentError, R>) -> Self {
+        match err {
+            ::aws_smithy_runtime_api::client::result::SdkError::ServiceError(context) => Self::from(context.into_err()),
+            _ => Error::Unhandled(
+                                        crate::error::sealed_unhandled::Unhandled {
+                                            meta: ::aws_smithy_types::error::metadata::ProvideErrorMetadata::meta(&err).clone(),
+                                            source: err.into(),
+                                        }
+                                    ),
+        }
+    }
+}
+impl From<crate::operation::refund_pb_account_payment::RefundPBAccountPaymentError> for Error {
+    fn from(err: crate::operation::refund_pb_account_payment::RefundPBAccountPaymentError) -> Self {
+        match err {
+            crate::operation::refund_pb_account_payment::RefundPBAccountPaymentError::AccountNotFoundError(inner) => Error::AccountNotFoundError(inner),
+            crate::operation::refund_pb_account_payment::RefundPBAccountPaymentError::Unhandled(inner) => Error::Unhandled(inner),
+        }
+    }
+}
 impl<R> From<::aws_smithy_runtime_api::client::result::SdkError<crate::operation::reverse_normal_account_transfer::ReverseNormalAccountTransferError, R>> for Error where R: Send + Sync + std::fmt::Debug + 'static {
     fn from(err: ::aws_smithy_runtime_api::client::result::SdkError<crate::operation::reverse_normal_account_transfer::ReverseNormalAccountTransferError, R>) -> Self {
         match err {

crates/pba_client/src/operation.rs

@@ -75,6 +75,9 @@ pub mod post_normal_account_transfer;
 /// Types for the `PostPBAccountDeposit` operation.
 pub mod post_pb_account_deposit;
 
+/// Types for the `RefundPBAccountPayment` operation.
+pub mod refund_pb_account_payment;
+
 /// Types for the `ReverseNormalAccountTransfer` operation.
 pub mod reverse_normal_account_transfer;