@augustusbank/typescript-sdk 0.21.0 → 0.22.1

package/src/resources/payouts.ts

@@ -9,6 +9,16 @@ import { path } from '../internal/utils/path';
 export 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> {
     return this._client.post('/v1/payouts', { body, ...options });
@@ -16,6 +26,13 @@ export class Payouts extends APIResource {
 
   /**
    * 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> {
     return this._client.get(path`/v1/payouts/${id}`, options);
@@ -23,6 +40,14 @@ export class Payouts extends APIResource {
 
   /**
    * 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 = {},
@@ -40,34 +65,35 @@ export interface PayoutCreateResponse {
    */
   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.
+   * Failure details when status is failed, otherwise null.
    */
-  destination:
-    | PayoutCreateResponse.IbanFinancialAddress
-    | PayoutCreateResponse.SortCodeFinancialAddress
-    | PayoutCreateResponse.AbaFinancialAddress
-    | PayoutCreateResponse.CryptoWalletFinancialAddress;
+  failure: PayoutCreateResponse.Failure | null;
 
   /**
-   * Failure details when status is failed, otherwise null.
+   * ISO 8601 UTC timestamp when the payout was initiated.
    */
-  failure: PayoutCreateResponse.Failure | null;
+  initiated_at: string;
 
   /**
    * Key-value pairs stored with the payout.
@@ -75,19 +101,48 @@ export interface PayoutCreateResponse {
   metadata: { [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.
@@ -95,103 +150,13 @@ export interface PayoutCreateResponse {
   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 namespace PayoutCreateResponse {
-  export 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';
-  }
-
-  export 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';
-  }
-
-  export 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';
-  }
-
-  export 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.
    */
@@ -204,6 +169,7 @@ export namespace PayoutCreateResponse {
       | 'account_blocked'
       | 'insufficient_funds'
       | 'invalid_account_format'
+      | 'invalid_routing_number'
       | 'invalid_instruction'
       | 'invalid_amount'
       | 'invalid_time'
@@ -233,34 +199,35 @@ export interface PayoutRetrieveResponse {
    */
   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.
+   * Failure details when status is failed, otherwise null.
    */
-  destination:
-    | PayoutRetrieveResponse.IbanFinancialAddress
-    | PayoutRetrieveResponse.SortCodeFinancialAddress
-    | PayoutRetrieveResponse.AbaFinancialAddress
-    | PayoutRetrieveResponse.CryptoWalletFinancialAddress;
+  failure: PayoutRetrieveResponse.Failure | null;
 
   /**
-   * Failure details when status is failed, otherwise null.
+   * ISO 8601 UTC timestamp when the payout was initiated.
    */
-  failure: PayoutRetrieveResponse.Failure | null;
+  initiated_at: string;
 
   /**
    * Key-value pairs stored with the payout.
@@ -268,19 +235,48 @@ export interface PayoutRetrieveResponse {
   metadata: { [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.
@@ -288,103 +284,13 @@ export interface PayoutRetrieveResponse {
   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 namespace PayoutRetrieveResponse {
-  export 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';
-  }
-
-  export 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';
-  }
-
-  export 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';
-  }
-
-  export 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.
    */
@@ -397,6 +303,7 @@ export namespace PayoutRetrieveResponse {
       | 'account_blocked'
       | 'insufficient_funds'
       | 'invalid_account_format'
+      | 'invalid_routing_number'
       | 'invalid_instruction'
       | 'invalid_amount'
       | 'invalid_time'
@@ -426,34 +333,35 @@ export interface PayoutListResponse {
    */
   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.
+   * Failure details when status is failed, otherwise null.
    */
-  destination:
-    | PayoutListResponse.IbanFinancialAddress
-    | PayoutListResponse.SortCodeFinancialAddress
-    | PayoutListResponse.AbaFinancialAddress
-    | PayoutListResponse.CryptoWalletFinancialAddress;
+  failure: PayoutListResponse.Failure | null;
 
   /**
-   * Failure details when status is failed, otherwise null.
+   * ISO 8601 UTC timestamp when the payout was initiated.
    */
-  failure: PayoutListResponse.Failure | null;
+  initiated_at: string;
 
   /**
    * Key-value pairs stored with the payout.
@@ -461,19 +369,48 @@ export interface PayoutListResponse {
   metadata: { [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.
@@ -481,103 +418,13 @@ export interface PayoutListResponse {
   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 namespace PayoutListResponse {
-  export 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';
-  }
-
-  export 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';
-  }
-
-  export 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';
-  }
-
-  export 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.
    */
@@ -590,6 +437,7 @@ export namespace PayoutListResponse {
       | 'account_blocked'
       | 'insufficient_funds'
       | 'invalid_account_format'
+      | 'invalid_routing_number'
       | 'invalid_instruction'
       | 'invalid_amount'
       | 'invalid_time'
@@ -615,136 +463,53 @@ export namespace PayoutListResponse {
 
 export interface PayoutCreateParams {
   /**
-   * Amount as a string decimal (e.g. "100.50").
+   * ID of the account to debit.
    */
-  amount: string;
+  account_id: string;
 
   /**
-   * Currency for the payout.
+   * Amount as a string decimal (e.g. "100.50").
    */
-  currency: 'EUR' | 'GBP' | 'USD' | 'USDC';
+  amount: string;
 
   /**
-   * Bank account or crypto wallet to send funds to.
+   * ID of the saved counterparty that receives the money.
    */
-  destination:
-    | PayoutCreateParams.Iban
-    | PayoutCreateParams.SortCodeFinancialAddress
-    | PayoutCreateParams.AbaFinancialAddress
-    | PayoutCreateParams.CryptoWalletFinancialAddress;
+  counterparty_id: string;
 
   /**
-   * Payment reference.
+   * Currency code (ISO 4217 or crypto).
    */
-  reference: string;
+  currency: 'EUR' | 'GBP' | 'USD' | 'USDC';
 
   /**
-   * ID of the account to debit.
+   * Key-value pairs stored with the payout.
    */
-  source_account_id: string;
+  metadata?: { [key: string]: string } | null;
 
   /**
-   * Key-value pairs stored with the payout.
+   * Settlement rail the counterparty is reachable on. Selected automatically when
+   * omitted. Validated against the counterparty financial address at runtime.
    */
-  metadata?: { [key: string]: string };
+  rail?:
+    | 'sepa'
+    | 'sepa_instant'
+    | 'faster_payments'
+    | 'swift'
+    | 'ach'
+    | 'fedwire'
+    | 'ethereum'
+    | 'ethereum_sepolia'
+    | 'solana'
+    | 'solana_devnet'
+    | 'polygon'
+    | 'polygon_amoy';
 
   /**
-   * Payment rail. It is enforced when provided, otherwise auto-selected.
+   * Unstructured remittance information attached to the transfer. This appears on
+   * the counterparty's bank statement. Not supported by blockchain rails.
    */
-  rail?: 'sepa_instant' | 'sepa' | 'faster_payments';
-}
-
-export namespace PayoutCreateParams {
-  export 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;
-  }
-
-  export 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';
-  }
-
-  export 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';
-  }
-
-  export 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';
-  }
+  unstructured_remittance_information?: string | null;
 }
 
 export interface PayoutListParams extends CursorPageParams {
@@ -759,7 +524,7 @@ export interface PayoutListParams extends CursorPageParams {
   /**
    * Filter by payout status.
    */
-  status?: 'pending' | 'paid' | 'failed';
+  status?: 'initiated' | 'submitted' | 'sent' | 'failed' | 'returned';
 }
 
 export namespace PayoutListParams {