@augustusbank/typescript-sdk 0.21.0 → 0.22.1

package/resources/payouts.d.mts

@@ -5,14 +5,39 @@ import { RequestOptions } from "../internal/request-options.mjs";
 export declare class Payouts extends APIResource {
     /**
      * Creates a new payout.
+     *
+     * @example
+     * ```ts
+     * const payout = await client.payouts.create({
+     *   account_id: '550e8400-e29b-41d4-a716-44665544000b',
+     *   amount: '100.50',
+     *   counterparty_id: '550e8400-e29b-41d4-a716-446655440000',
+     *   currency: 'EUR',
+     * });
+     * ```
      */
     create(body: PayoutCreateParams, options?: RequestOptions): APIPromise<PayoutCreateResponse>;
     /**
      * Retrieves a payout by ID.
+     *
+     * @example
+     * ```ts
+     * const payout = await client.payouts.retrieve(
+     *   '550e8400-e29b-41d4-a716-446655440003',
+     * );
+     * ```
      */
     retrieve(id: string, options?: RequestOptions): APIPromise<PayoutRetrieveResponse>;
     /**
      * Lists payouts for the merchant with cursor-based pagination.
+     *
+     * @example
+     * ```ts
+     * // Automatically fetches more pages as needed.
+     * for await (const payoutListResponse of client.payouts.list()) {
+     *   // ...
+     * }
+     * ```
      */
     list(query?: PayoutListParams | null | undefined, options?: RequestOptions): PagePromise<PayoutListResponsesCursorPage, PayoutListResponse>;
 }
@@ -22,26 +47,30 @@ export interface PayoutCreateResponse {
      * Unique identifier of the payout.
      */
     id: string;
+    /**
+     * ID of the account that was debited.
+     */
+    account_id: string;
     /**
      * Amount as a string decimal (e.g. "100.50").
      */
     amount: string;
     /**
-     * ISO 8601 UTC timestamp when the payout was created.
+     * ID of the counterparty that receives the money.
      */
-    created_at: string;
+    counterparty_id: string;
     /**
-     * Currency code (ISO 4217 currency code or crypto currency code).
+     * Currency code (ISO 4217 or crypto).
      */
     currency: 'EUR' | 'GBP' | 'USD' | 'USDC';
-    /**
-     * Bank account or crypto wallet the payout was sent to.
-     */
-    destination: PayoutCreateResponse.IbanFinancialAddress | PayoutCreateResponse.SortCodeFinancialAddress | PayoutCreateResponse.AbaFinancialAddress | PayoutCreateResponse.CryptoWalletFinancialAddress;
     /**
      * Failure details when status is failed, otherwise null.
      */
     failure: PayoutCreateResponse.Failure | null;
+    /**
+     * ISO 8601 UTC timestamp when the payout was initiated.
+     */
+    initiated_at: string;
     /**
      * Key-value pairs stored with the payout.
      */
@@ -49,95 +78,38 @@ export interface PayoutCreateResponse {
         [key: string]: string;
     };
     /**
-     * Payment reference.
+     * Payment scheme or blockchain used for the payout, or null when unknown.
      */
-    reference: string;
+    rail: 'sepa' | 'sepa_instant' | 'faster_payments' | 'swift' | 'internal' | 'target' | 'ach' | 'fedwire' | 'bitcoin' | 'bitcoin_testnet4' | 'ethereum' | 'ethereum_sepolia' | 'solana' | 'solana_devnet' | 'polygon' | 'polygon_amoy' | null;
     /**
-     * ID of the account that was debited.
+     * ISO 8601 UTC timestamp when the payout was sent.
      */
-    source_account_id: string;
+    sent_at: string | null;
     /**
      * Current status of the payout.
      */
-    status: 'pending' | 'paid' | 'failed' | 'returned';
+    status: 'initiated' | 'submitted' | 'sent' | 'failed' | 'returned';
+    /**
+     * Reference used to track the payment across the payment network, such as the UETR
+     * for SWIFT payments.
+     */
+    tracking_reference: string | null;
+    /**
+     * Transaction hash for crypto payouts, or null when not known. Only blockchain
+     * rails support this field.
+     */
+    tx_hash: string | null;
     /**
      * Resource type discriminator.
      */
     type: 'payout';
     /**
-     * ISO 8601 UTC timestamp when the payout was last updated.
+     * Unstructured remittance information attached to the transfer. Not all rails
+     * support this field.
      */
-    updated_at: string;
+    unstructured_remittance_information: string | null;
 }
 export declare namespace PayoutCreateResponse {
-    interface IbanFinancialAddress {
-        /**
-         * Name of the account holder.
-         */
-        account_holder_name: string;
-        /**
-         * Bank Identifier Code, or null if not provided.
-         */
-        bic: string | null;
-        /**
-         * International Bank Account Number.
-         */
-        iban: string;
-        /**
-         * Discriminator for IBAN financial address.
-         */
-        type: 'iban';
-    }
-    interface SortCodeFinancialAddress {
-        /**
-         * Name of the account holder.
-         */
-        account_holder_name: string;
-        /**
-         * UK account number (8 digits).
-         */
-        account_number: string;
-        /**
-         * UK sort code (6 digits).
-         */
-        sort_code: string;
-        /**
-         * Discriminator for UK sort code financial address.
-         */
-        type: 'sort_code';
-    }
-    interface AbaFinancialAddress {
-        /**
-         * Name of the account holder.
-         */
-        account_holder_name: string;
-        /**
-         * Bank account number.
-         */
-        account_number: string;
-        /**
-         * ABA routing number (9 digits).
-         */
-        routing_number: string;
-        /**
-         * Discriminator for ABA wire financial address.
-         */
-        type: 'aba';
-    }
-    interface CryptoWalletFinancialAddress {
-        /**
-         * Wallet address on the specified blockchain.
-         */
-        address: string;
-        /**
-         * Blockchain network for the crypto wallet.
-         */
-        blockchain: 'bitcoin' | 'ethereum' | 'solana' | 'polygon' | 'bitcoin_testnet4' | 'ethereum_sepolia' | 'solana_devnet' | 'polygon_amoy';
-        /**
-         * Discriminator for crypto wallet financial address.
-         */
-        type: 'crypto_wallet';
-    }
     /**
      * Failure details when status is failed, otherwise null.
      */
@@ -145,7 +117,7 @@ export declare namespace PayoutCreateResponse {
         /**
          * Failure code.
          */
-        code: 'account_closed' | 'account_blocked' | 'insufficient_funds' | 'invalid_account_format' | 'invalid_instruction' | 'invalid_amount' | 'invalid_time' | 'duplicate_transaction' | 'payee_verification_failed' | 'system_error' | 'provider_system_error' | 'rejected_by_correspondent_bank' | 'blocked_by_review' | 'unknown';
+        code: 'account_closed' | 'account_blocked' | 'insufficient_funds' | 'invalid_account_format' | 'invalid_routing_number' | 'invalid_instruction' | 'invalid_amount' | 'invalid_time' | 'duplicate_transaction' | 'payee_verification_failed' | 'system_error' | 'provider_system_error' | 'rejected_by_correspondent_bank' | 'blocked_by_review' | 'unknown';
         /**
          * Human-readable description of the failure.
          */
@@ -161,26 +133,30 @@ export interface PayoutRetrieveResponse {
      * Unique identifier of the payout.
      */
     id: string;
+    /**
+     * ID of the account that was debited.
+     */
+    account_id: string;
     /**
      * Amount as a string decimal (e.g. "100.50").
      */
     amount: string;
     /**
-     * ISO 8601 UTC timestamp when the payout was created.
+     * ID of the counterparty that receives the money.
      */
-    created_at: string;
+    counterparty_id: string;
     /**
-     * Currency code (ISO 4217 currency code or crypto currency code).
+     * Currency code (ISO 4217 or crypto).
      */
     currency: 'EUR' | 'GBP' | 'USD' | 'USDC';
-    /**
-     * Bank account or crypto wallet the payout was sent to.
-     */
-    destination: PayoutRetrieveResponse.IbanFinancialAddress | PayoutRetrieveResponse.SortCodeFinancialAddress | PayoutRetrieveResponse.AbaFinancialAddress | PayoutRetrieveResponse.CryptoWalletFinancialAddress;
     /**
      * Failure details when status is failed, otherwise null.
      */
     failure: PayoutRetrieveResponse.Failure | null;
+    /**
+     * ISO 8601 UTC timestamp when the payout was initiated.
+     */
+    initiated_at: string;
     /**
      * Key-value pairs stored with the payout.
      */
@@ -188,95 +164,38 @@ export interface PayoutRetrieveResponse {
         [key: string]: string;
     };
     /**
-     * Payment reference.
+     * Payment scheme or blockchain used for the payout, or null when unknown.
      */
-    reference: string;
+    rail: 'sepa' | 'sepa_instant' | 'faster_payments' | 'swift' | 'internal' | 'target' | 'ach' | 'fedwire' | 'bitcoin' | 'bitcoin_testnet4' | 'ethereum' | 'ethereum_sepolia' | 'solana' | 'solana_devnet' | 'polygon' | 'polygon_amoy' | null;
     /**
-     * ID of the account that was debited.
+     * ISO 8601 UTC timestamp when the payout was sent.
      */
-    source_account_id: string;
+    sent_at: string | null;
     /**
      * Current status of the payout.
      */
-    status: 'pending' | 'paid' | 'failed' | 'returned';
+    status: 'initiated' | 'submitted' | 'sent' | 'failed' | 'returned';
+    /**
+     * Reference used to track the payment across the payment network, such as the UETR
+     * for SWIFT payments.
+     */
+    tracking_reference: string | null;
+    /**
+     * Transaction hash for crypto payouts, or null when not known. Only blockchain
+     * rails support this field.
+     */
+    tx_hash: string | null;
     /**
      * Resource type discriminator.
      */
     type: 'payout';
     /**
-     * ISO 8601 UTC timestamp when the payout was last updated.
+     * Unstructured remittance information attached to the transfer. Not all rails
+     * support this field.
      */
-    updated_at: string;
+    unstructured_remittance_information: string | null;
 }
 export declare namespace PayoutRetrieveResponse {
-    interface IbanFinancialAddress {
-        /**
-         * Name of the account holder.
-         */
-        account_holder_name: string;
-        /**
-         * Bank Identifier Code, or null if not provided.
-         */
-        bic: string | null;
-        /**
-         * International Bank Account Number.
-         */
-        iban: string;
-        /**
-         * Discriminator for IBAN financial address.
-         */
-        type: 'iban';
-    }
-    interface SortCodeFinancialAddress {
-        /**
-         * Name of the account holder.
-         */
-        account_holder_name: string;
-        /**
-         * UK account number (8 digits).
-         */
-        account_number: string;
-        /**
-         * UK sort code (6 digits).
-         */
-        sort_code: string;
-        /**
-         * Discriminator for UK sort code financial address.
-         */
-        type: 'sort_code';
-    }
-    interface AbaFinancialAddress {
-        /**
-         * Name of the account holder.
-         */
-        account_holder_name: string;
-        /**
-         * Bank account number.
-         */
-        account_number: string;
-        /**
-         * ABA routing number (9 digits).
-         */
-        routing_number: string;
-        /**
-         * Discriminator for ABA wire financial address.
-         */
-        type: 'aba';
-    }
-    interface CryptoWalletFinancialAddress {
-        /**
-         * Wallet address on the specified blockchain.
-         */
-        address: string;
-        /**
-         * Blockchain network for the crypto wallet.
-         */
-        blockchain: 'bitcoin' | 'ethereum' | 'solana' | 'polygon' | 'bitcoin_testnet4' | 'ethereum_sepolia' | 'solana_devnet' | 'polygon_amoy';
-        /**
-         * Discriminator for crypto wallet financial address.
-         */
-        type: 'crypto_wallet';
-    }
     /**
      * Failure details when status is failed, otherwise null.
      */
@@ -284,7 +203,7 @@ export declare namespace PayoutRetrieveResponse {
         /**
          * Failure code.
          */
-        code: 'account_closed' | 'account_blocked' | 'insufficient_funds' | 'invalid_account_format' | 'invalid_instruction' | 'invalid_amount' | 'invalid_time' | 'duplicate_transaction' | 'payee_verification_failed' | 'system_error' | 'provider_system_error' | 'rejected_by_correspondent_bank' | 'blocked_by_review' | 'unknown';
+        code: 'account_closed' | 'account_blocked' | 'insufficient_funds' | 'invalid_account_format' | 'invalid_routing_number' | 'invalid_instruction' | 'invalid_amount' | 'invalid_time' | 'duplicate_transaction' | 'payee_verification_failed' | 'system_error' | 'provider_system_error' | 'rejected_by_correspondent_bank' | 'blocked_by_review' | 'unknown';
         /**
          * Human-readable description of the failure.
          */
@@ -300,26 +219,30 @@ export interface PayoutListResponse {
      * Unique identifier of the payout.
      */
     id: string;
+    /**
+     * ID of the account that was debited.
+     */
+    account_id: string;
     /**
      * Amount as a string decimal (e.g. "100.50").
      */
     amount: string;
     /**
-     * ISO 8601 UTC timestamp when the payout was created.
+     * ID of the counterparty that receives the money.
      */
-    created_at: string;
+    counterparty_id: string;
     /**
-     * Currency code (ISO 4217 currency code or crypto currency code).
+     * Currency code (ISO 4217 or crypto).
      */
     currency: 'EUR' | 'GBP' | 'USD' | 'USDC';
-    /**
-     * Bank account or crypto wallet the payout was sent to.
-     */
-    destination: PayoutListResponse.IbanFinancialAddress | PayoutListResponse.SortCodeFinancialAddress | PayoutListResponse.AbaFinancialAddress | PayoutListResponse.CryptoWalletFinancialAddress;
     /**
      * Failure details when status is failed, otherwise null.
      */
     failure: PayoutListResponse.Failure | null;
+    /**
+     * ISO 8601 UTC timestamp when the payout was initiated.
+     */
+    initiated_at: string;
     /**
      * Key-value pairs stored with the payout.
      */
@@ -327,95 +250,38 @@ export interface PayoutListResponse {
         [key: string]: string;
     };
     /**
-     * Payment reference.
+     * Payment scheme or blockchain used for the payout, or null when unknown.
      */
-    reference: string;
+    rail: 'sepa' | 'sepa_instant' | 'faster_payments' | 'swift' | 'internal' | 'target' | 'ach' | 'fedwire' | 'bitcoin' | 'bitcoin_testnet4' | 'ethereum' | 'ethereum_sepolia' | 'solana' | 'solana_devnet' | 'polygon' | 'polygon_amoy' | null;
     /**
-     * ID of the account that was debited.
+     * ISO 8601 UTC timestamp when the payout was sent.
      */
-    source_account_id: string;
+    sent_at: string | null;
     /**
      * Current status of the payout.
      */
-    status: 'pending' | 'paid' | 'failed' | 'returned';
+    status: 'initiated' | 'submitted' | 'sent' | 'failed' | 'returned';
+    /**
+     * Reference used to track the payment across the payment network, such as the UETR
+     * for SWIFT payments.
+     */
+    tracking_reference: string | null;
+    /**
+     * Transaction hash for crypto payouts, or null when not known. Only blockchain
+     * rails support this field.
+     */
+    tx_hash: string | null;
     /**
      * Resource type discriminator.
      */
     type: 'payout';
     /**
-     * ISO 8601 UTC timestamp when the payout was last updated.
+     * Unstructured remittance information attached to the transfer. Not all rails
+     * support this field.
      */
-    updated_at: string;
+    unstructured_remittance_information: string | null;
 }
 export declare namespace PayoutListResponse {
-    interface IbanFinancialAddress {
-        /**
-         * Name of the account holder.
-         */
-        account_holder_name: string;
-        /**
-         * Bank Identifier Code, or null if not provided.
-         */
-        bic: string | null;
-        /**
-         * International Bank Account Number.
-         */
-        iban: string;
-        /**
-         * Discriminator for IBAN financial address.
-         */
-        type: 'iban';
-    }
-    interface SortCodeFinancialAddress {
-        /**
-         * Name of the account holder.
-         */
-        account_holder_name: string;
-        /**
-         * UK account number (8 digits).
-         */
-        account_number: string;
-        /**
-         * UK sort code (6 digits).
-         */
-        sort_code: string;
-        /**
-         * Discriminator for UK sort code financial address.
-         */
-        type: 'sort_code';
-    }
-    interface AbaFinancialAddress {
-        /**
-         * Name of the account holder.
-         */
-        account_holder_name: string;
-        /**
-         * Bank account number.
-         */
-        account_number: string;
-        /**
-         * ABA routing number (9 digits).
-         */
-        routing_number: string;
-        /**
-         * Discriminator for ABA wire financial address.
-         */
-        type: 'aba';
-    }
-    interface CryptoWalletFinancialAddress {
-        /**
-         * Wallet address on the specified blockchain.
-         */
-        address: string;
-        /**
-         * Blockchain network for the crypto wallet.
-         */
-        blockchain: 'bitcoin' | 'ethereum' | 'solana' | 'polygon' | 'bitcoin_testnet4' | 'ethereum_sepolia' | 'solana_devnet' | 'polygon_amoy';
-        /**
-         * Discriminator for crypto wallet financial address.
-         */
-        type: 'crypto_wallet';
-    }
     /**
      * Failure details when status is failed, otherwise null.
      */
@@ -423,7 +289,7 @@ export declare namespace PayoutListResponse {
         /**
          * Failure code.
          */
-        code: 'account_closed' | 'account_blocked' | 'insufficient_funds' | 'invalid_account_format' | 'invalid_instruction' | 'invalid_amount' | 'invalid_time' | 'duplicate_transaction' | 'payee_verification_failed' | 'system_error' | 'provider_system_error' | 'rejected_by_correspondent_bank' | 'blocked_by_review' | 'unknown';
+        code: 'account_closed' | 'account_blocked' | 'insufficient_funds' | 'invalid_account_format' | 'invalid_routing_number' | 'invalid_instruction' | 'invalid_amount' | 'invalid_time' | 'duplicate_transaction' | 'payee_verification_failed' | 'system_error' | 'provider_system_error' | 'rejected_by_correspondent_bank' | 'blocked_by_review' | 'unknown';
         /**
          * Human-readable description of the failure.
          */
@@ -436,105 +302,37 @@ export declare namespace PayoutListResponse {
 }
 export interface PayoutCreateParams {
     /**
-     * Amount as a string decimal (e.g. "100.50").
-     */
-    amount: string;
-    /**
-     * Currency for the payout.
+     * ID of the account to debit.
      */
-    currency: 'EUR' | 'GBP' | 'USD' | 'USDC';
+    account_id: string;
     /**
-     * Bank account or crypto wallet to send funds to.
+     * Amount as a string decimal (e.g. "100.50").
      */
-    destination: PayoutCreateParams.Iban | PayoutCreateParams.SortCodeFinancialAddress | PayoutCreateParams.AbaFinancialAddress | PayoutCreateParams.CryptoWalletFinancialAddress;
+    amount: string;
     /**
-     * Payment reference.
+     * ID of the saved counterparty that receives the money.
      */
-    reference: string;
+    counterparty_id: string;
     /**
-     * ID of the account to debit.
+     * Currency code (ISO 4217 or crypto).
      */
-    source_account_id: string;
+    currency: 'EUR' | 'GBP' | 'USD' | 'USDC';
     /**
      * Key-value pairs stored with the payout.
      */
     metadata?: {
         [key: string]: string;
-    };
+    } | null;
     /**
-     * Payment rail. It is enforced when provided, otherwise auto-selected.
+     * Settlement rail the counterparty is reachable on. Selected automatically when
+     * omitted. Validated against the counterparty financial address at runtime.
      */
-    rail?: 'sepa_instant' | 'sepa' | 'faster_payments';
-}
-export declare namespace PayoutCreateParams {
-    interface Iban {
-        /**
-         * Name of the account holder.
-         */
-        account_holder_name: string;
-        /**
-         * International Bank Account Number.
-         */
-        iban: string;
-        /**
-         * Discriminator for IBAN financial address.
-         */
-        type: 'iban';
-        /**
-         * Bank Identifier Code.
-         */
-        bic?: string;
-    }
-    interface SortCodeFinancialAddress {
-        /**
-         * Name of the account holder.
-         */
-        account_holder_name: string;
-        /**
-         * UK account number (8 digits).
-         */
-        account_number: string;
-        /**
-         * UK sort code (6 digits).
-         */
-        sort_code: string;
-        /**
-         * Discriminator for UK sort code financial address.
-         */
-        type: 'sort_code';
-    }
-    interface AbaFinancialAddress {
-        /**
-         * Name of the account holder.
-         */
-        account_holder_name: string;
-        /**
-         * Bank account number.
-         */
-        account_number: string;
-        /**
-         * ABA routing number (9 digits).
-         */
-        routing_number: string;
-        /**
-         * Discriminator for ABA wire financial address.
-         */
-        type: 'aba';
-    }
-    interface CryptoWalletFinancialAddress {
-        /**
-         * Wallet address on the specified blockchain.
-         */
-        address: string;
-        /**
-         * Blockchain network for the crypto wallet.
-         */
-        blockchain: 'bitcoin' | 'ethereum' | 'solana' | 'polygon' | 'bitcoin_testnet4' | 'ethereum_sepolia' | 'solana_devnet' | 'polygon_amoy';
-        /**
-         * Discriminator for crypto wallet financial address.
-         */
-        type: 'crypto_wallet';
-    }
+    rail?: 'sepa' | 'sepa_instant' | 'faster_payments' | 'swift' | 'ach' | 'fedwire' | 'ethereum' | 'ethereum_sepolia' | 'solana' | 'solana_devnet' | 'polygon' | 'polygon_amoy';
+    /**
+     * Unstructured remittance information attached to the transfer. This appears on
+     * the counterparty's bank statement. Not supported by blockchain rails.
+     */
+    unstructured_remittance_information?: string | null;
 }
 export interface PayoutListParams extends CursorPageParams {
     created_at?: PayoutListParams.CreatedAt;
@@ -546,7 +344,7 @@ export interface PayoutListParams extends CursorPageParams {
     /**
      * Filter by payout status.
      */
-    status?: 'pending' | 'paid' | 'failed';
+    status?: 'initiated' | 'submitted' | 'sent' | 'failed' | 'returned';
 }
 export declare namespace PayoutListParams {
     interface CreatedAt {