@naturalpay/sdk 0.9.0 → 0.11.0

package/src/resources/payment-requests.ts

@@ -17,8 +17,10 @@ export class PaymentRequests extends APIResource {
    * ```ts
    * const paymentRequest = await client.paymentRequests.create({
    *   amount: 1,
-   *   payer: { type: 'type', value: 'dev@stainless.com' },
+   *   payer: { type: 'email', value: 'dev@stainless.com' },
    *   'Idempotency-Key': 'Idempotency-Key',
+   *   'X-Agent-ID': 'X-Agent-ID',
+   *   'X-Instance-ID': 'X-Instance-ID',
    * });
    * ```
    */
@@ -36,11 +38,7 @@ export class PaymentRequests extends APIResource {
       body,
       ...options,
       headers: buildHeaders([
-        {
-          'Idempotency-Key': idempotencyKey,
-          ...(xAgentID != null ? { 'X-Agent-ID': xAgentID } : undefined),
-          ...(xInstanceID != null ? { 'X-Instance-ID': xInstanceID } : undefined),
-        },
+        { 'Idempotency-Key': idempotencyKey, 'X-Agent-ID': xAgentID, 'X-Instance-ID': xInstanceID },
         options?.headers,
       ]),
     });
@@ -51,24 +49,18 @@ export class PaymentRequests extends APIResource {
    *
    * @example
    * ```ts
-   * const paymentRequests = await client.paymentRequests.list();
+   * const paymentRequests = await client.paymentRequests.list({
+   *   'X-Agent-ID': 'X-Agent-ID',
+   *   'X-Instance-ID': 'X-Instance-ID',
+   * });
    * ```
    */
-  list(
-    params: PaymentRequestListParams | null | undefined = {},
-    options?: RequestOptions,
-  ): APIPromise<PaymentRequestListResponse> {
-    const { 'X-Agent-ID': xAgentID, 'X-Instance-ID': xInstanceID, ...query } = params ?? {};
+  list(params: PaymentRequestListParams, options?: RequestOptions): APIPromise<PaymentRequestListResponse> {
+    const { 'X-Agent-ID': xAgentID, 'X-Instance-ID': xInstanceID, ...query } = params;
     return this._client.get('/payment-requests', {
       query,
       ...options,
-      headers: buildHeaders([
-        {
-          ...(xAgentID != null ? { 'X-Agent-ID': xAgentID } : undefined),
-          ...(xInstanceID != null ? { 'X-Instance-ID': xInstanceID } : undefined),
-        },
-        options?.headers,
-      ]),
+      headers: buildHeaders([{ 'X-Agent-ID': xAgentID, 'X-Instance-ID': xInstanceID }, options?.headers]),
     });
   }
 
@@ -80,7 +72,11 @@ export class PaymentRequests extends APIResource {
    * ```ts
    * const response = await client.paymentRequests.decline(
    *   'prq_ecc2efdd09bd231a9ad9bd2aada37aa7',
-   *   { 'Idempotency-Key': 'Idempotency-Key' },
+   *   {
+   *     'Idempotency-Key': 'Idempotency-Key',
+   *     'X-Agent-ID': 'X-Agent-ID',
+   *     'X-Instance-ID': 'X-Instance-ID',
+   *   },
    * );
    * ```
    */
@@ -97,11 +93,7 @@ export class PaymentRequests extends APIResource {
     return this._client.post(path`/payment-requests/${paymentRequestID}/decline`, {
       ...options,
       headers: buildHeaders([
-        {
-          'Idempotency-Key': idempotencyKey,
-          ...(xAgentID != null ? { 'X-Agent-ID': xAgentID } : undefined),
-          ...(xInstanceID != null ? { 'X-Instance-ID': xInstanceID } : undefined),
-        },
+        { 'Idempotency-Key': idempotencyKey, 'X-Agent-ID': xAgentID, 'X-Instance-ID': xInstanceID },
         options?.headers,
       ]),
     });
@@ -116,10 +108,12 @@ export class PaymentRequests extends APIResource {
    *   'prq_ecc2efdd09bd231a9ad9bd2aada37aa7',
    *   {
    *     paymentSource: {
-   *       type: 'type',
+   *       type: 'wallet',
    *       walletId: 'wal_ecc2efdd09bd231a9ad9bd2aada37aa7',
    *     },
    *     'Idempotency-Key': 'Idempotency-Key',
+   *     'X-Agent-ID': 'X-Agent-ID',
+   *     'X-Instance-ID': 'X-Instance-ID',
    *   },
    * );
    * ```
@@ -139,11 +133,7 @@ export class PaymentRequests extends APIResource {
       body,
       ...options,
       headers: buildHeaders([
-        {
-          'Idempotency-Key': idempotencyKey,
-          ...(xAgentID != null ? { 'X-Agent-ID': xAgentID } : undefined),
-          ...(xInstanceID != null ? { 'X-Instance-ID': xInstanceID } : undefined),
-        },
+        { 'Idempotency-Key': idempotencyKey, 'X-Agent-ID': xAgentID, 'X-Instance-ID': xInstanceID },
         options?.headers,
       ]),
     });
@@ -156,24 +146,22 @@ export class PaymentRequests extends APIResource {
    * ```ts
    * const paymentRequest = await client.paymentRequests.get(
    *   'prq_ecc2efdd09bd231a9ad9bd2aada37aa7',
+   *   {
+   *     'X-Agent-ID': 'X-Agent-ID',
+   *     'X-Instance-ID': 'X-Instance-ID',
+   *   },
    * );
    * ```
    */
   get(
     paymentRequestID: string,
-    params: PaymentRequestGetParams | null | undefined = {},
+    params: PaymentRequestGetParams,
     options?: RequestOptions,
   ): APIPromise<PaymentRequestGetResponse> {
-    const { 'X-Agent-ID': xAgentID, 'X-Instance-ID': xInstanceID } = params ?? {};
+    const { 'X-Agent-ID': xAgentID, 'X-Instance-ID': xInstanceID } = params;
     return this._client.get(path`/payment-requests/${paymentRequestID}`, {
       ...options,
-      headers: buildHeaders([
-        {
-          ...(xAgentID != null ? { 'X-Agent-ID': xAgentID } : undefined),
-          ...(xInstanceID != null ? { 'X-Instance-ID': xInstanceID } : undefined),
-        },
-        options?.headers,
-      ]),
+      headers: buildHeaders([{ 'X-Agent-ID': xAgentID, 'X-Instance-ID': xInstanceID }, options?.headers]),
     });
   }
 
@@ -182,25 +170,21 @@ export class PaymentRequests extends APIResource {
    *
    * @example
    * ```ts
-   * const response =
-   *   await client.paymentRequests.listIncoming();
+   * const response = await client.paymentRequests.listIncoming({
+   *   'X-Agent-ID': 'X-Agent-ID',
+   *   'X-Instance-ID': 'X-Instance-ID',
+   * });
    * ```
    */
   listIncoming(
-    params: PaymentRequestListIncomingParams | null | undefined = {},
+    params: PaymentRequestListIncomingParams,
     options?: RequestOptions,
   ): APIPromise<PaymentRequestListIncomingResponse> {
-    const { 'X-Agent-ID': xAgentID, 'X-Instance-ID': xInstanceID, ...query } = params ?? {};
+    const { 'X-Agent-ID': xAgentID, 'X-Instance-ID': xInstanceID, ...query } = params;
     return this._client.get('/payment-requests/incoming', {
       query,
       ...options,
-      headers: buildHeaders([
-        {
-          ...(xAgentID != null ? { 'X-Agent-ID': xAgentID } : undefined),
-          ...(xInstanceID != null ? { 'X-Instance-ID': xInstanceID } : undefined),
-        },
-        options?.headers,
-      ]),
+      headers: buildHeaders([{ 'X-Agent-ID': xAgentID, 'X-Instance-ID': xInstanceID }, options?.headers]),
     });
   }
 }
@@ -229,7 +213,7 @@ export namespace PaymentRequestCreateResponse {
     /**
      * Resource type
      */
-    type: string;
+    type: 'paymentRequest';
   }
 
   export namespace Data {
@@ -305,7 +289,15 @@ export namespace PaymentRequestCreateResponse {
       /**
        * Current status of the payment request
        */
-      status: 'OPEN' | 'PROCESSING' | 'COMPLETED' | 'CANCELLED' | 'DECLINED' | 'EXPIRED';
+      status:
+        | 'OPEN'
+        | 'PROCESSING'
+        | 'COMPLETED'
+        | 'FAILED'
+        | 'RETURNED'
+        | 'CANCELLED'
+        | 'DECLINED'
+        | 'EXPIRED';
 
       /**
        * ID of the transaction created by the most recent payment attempt, or null if no
@@ -355,7 +347,7 @@ export namespace PaymentRequestCreateResponse {
           /**
            * Resource type
            */
-          type: string;
+          type: 'party';
         }
       }
 
@@ -379,7 +371,7 @@ export namespace PaymentRequestCreateResponse {
           /**
            * Resource type
            */
-          type: string;
+          type: 'party';
         }
       }
     }
@@ -412,7 +404,7 @@ export namespace PaymentRequestListResponse {
     /**
      * Resource type
      */
-    type: string;
+    type: 'paymentRequest';
   }
 
   export namespace Data {
@@ -488,7 +480,15 @@ export namespace PaymentRequestListResponse {
       /**
        * Current status of the payment request
        */
-      status: 'OPEN' | 'PROCESSING' | 'COMPLETED' | 'CANCELLED' | 'DECLINED' | 'EXPIRED';
+      status:
+        | 'OPEN'
+        | 'PROCESSING'
+        | 'COMPLETED'
+        | 'FAILED'
+        | 'RETURNED'
+        | 'CANCELLED'
+        | 'DECLINED'
+        | 'EXPIRED';
 
       /**
        * ID of the transaction created by the most recent payment attempt, or null if no
@@ -511,6 +511,11 @@ export namespace PaymentRequestListResponse {
        */
       payerParty: Relationships.PayerParty;
 
+      /**
+       * Payment submitted for this payment request, if one exists.
+       */
+      payment: Relationships.Payment;
+
       /**
        * Party requesting the payment
        */
@@ -543,7 +548,31 @@ export namespace PaymentRequestListResponse {
           /**
            * Resource type
            */
-          type: string;
+          type: 'party';
+        }
+      }
+
+      /**
+       * Payment submitted for this payment request, if one exists.
+       */
+      export interface Payment {
+        /**
+         * Related resource identifier
+         */
+        data: Payment.Data | null;
+      }
+
+      export namespace Payment {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: 'payment';
         }
       }
 
@@ -567,7 +596,7 @@ export namespace PaymentRequestListResponse {
           /**
            * Resource type
            */
-          type: string;
+          type: 'party';
         }
       }
 
@@ -591,7 +620,7 @@ export namespace PaymentRequestListResponse {
           /**
            * Resource type
            */
-          type: string;
+          type: 'wallet';
         }
       }
     }
@@ -634,7 +663,7 @@ export namespace PaymentRequestDeclineResponse {
     /**
      * Resource type
      */
-    type: string;
+    type: 'paymentRequest';
   }
 
   export namespace Data {
@@ -710,7 +739,15 @@ export namespace PaymentRequestDeclineResponse {
       /**
        * Current status of the payment request
        */
-      status: 'OPEN' | 'PROCESSING' | 'COMPLETED' | 'CANCELLED' | 'DECLINED' | 'EXPIRED';
+      status:
+        | 'OPEN'
+        | 'PROCESSING'
+        | 'COMPLETED'
+        | 'FAILED'
+        | 'RETURNED'
+        | 'CANCELLED'
+        | 'DECLINED'
+        | 'EXPIRED';
 
       /**
        * ID of the transaction created by the most recent payment attempt, or null if no
@@ -733,6 +770,11 @@ export namespace PaymentRequestDeclineResponse {
        */
       payerParty: Relationships.PayerParty;
 
+      /**
+       * Payment submitted for this payment request, if one exists.
+       */
+      payment: Relationships.Payment;
+
       /**
        * Party requesting the payment
        */
@@ -765,7 +807,31 @@ export namespace PaymentRequestDeclineResponse {
           /**
            * Resource type
            */
-          type: string;
+          type: 'party';
+        }
+      }
+
+      /**
+       * Payment submitted for this payment request, if one exists.
+       */
+      export interface Payment {
+        /**
+         * Related resource identifier
+         */
+        data: Payment.Data | null;
+      }
+
+      export namespace Payment {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: 'payment';
         }
       }
 
@@ -789,7 +855,7 @@ export namespace PaymentRequestDeclineResponse {
           /**
            * Resource type
            */
-          type: string;
+          type: 'party';
         }
       }
 
@@ -813,7 +879,7 @@ export namespace PaymentRequestDeclineResponse {
           /**
            * Resource type
            */
-          type: string;
+          type: 'wallet';
         }
       }
     }
@@ -828,14 +894,216 @@ export namespace PaymentRequestFulfillResponse {
   export interface Data {
     id: string;
 
+    /**
+     * Resource attributes
+     */
     attributes: Data.Attributes;
 
-    type: string;
+    /**
+     * Resource relationships
+     */
+    relationships: Data.Relationships;
+
+    type: 'payment';
   }
 
   export namespace Data {
+    /**
+     * Resource attributes
+     */
     export interface Attributes {
-      outcome: 'processing' | 'failed' | 'completed' | 'in_review';
+      /**
+       * Amount in cents
+       */
+      amount: number;
+
+      /**
+       * When this payment was created
+       */
+      createdAt: string;
+
+      /**
+       * Currency code
+       */
+      currency: string;
+
+      /**
+       * Payment description
+       */
+      description: string | null;
+
+      /**
+       * Payment status
+       */
+      status:
+        | 'CREATED'
+        | 'PROCESSING'
+        | 'PENDING_CLAIM'
+        | 'IN_REVIEW'
+        | 'COMPLETED'
+        | 'FAILED'
+        | 'RETURNED'
+        | 'APPROVAL_DENIED'
+        | 'CANCELLED';
+
+      /**
+       * When this payment was last updated
+       */
+      updatedAt: string | null;
+    }
+
+    /**
+     * Resource relationships
+     */
+    export interface Relationships {
+      /**
+       * Payment request that produced this payment, when applicable.
+       */
+      paymentRequest: Relationships.PaymentRequest;
+
+      /**
+       * Recipient party for this payment, when known.
+       */
+      recipient: Relationships.Recipient;
+
+      /**
+       * Recipient agent when the caller addressed an agent ID. Null otherwise, including
+       * when the recipient was addressed as an email, phone, or party ID.
+       */
+      recipientAgent: Relationships.RecipientAgent;
+
+      /**
+       * Party that initiated the payment
+       */
+      sender: Relationships.Sender;
+
+      /**
+       * Sender-side transaction row for this payment, when available.
+       */
+      transaction: Relationships.Transaction;
+    }
+
+    export namespace Relationships {
+      /**
+       * Payment request that produced this payment, when applicable.
+       */
+      export interface PaymentRequest {
+        /**
+         * Related resource identifier
+         */
+        data: PaymentRequest.Data | null;
+      }
+
+      export namespace PaymentRequest {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: 'paymentRequest';
+        }
+      }
+
+      /**
+       * Recipient party for this payment, when known.
+       */
+      export interface Recipient {
+        /**
+         * Related resource identifier
+         */
+        data: Recipient.Data | null;
+      }
+
+      export namespace Recipient {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: 'party';
+        }
+      }
+
+      /**
+       * Recipient agent when the caller addressed an agent ID. Null otherwise, including
+       * when the recipient was addressed as an email, phone, or party ID.
+       */
+      export interface RecipientAgent {
+        /**
+         * Related resource identifier
+         */
+        data: RecipientAgent.Data | null;
+      }
+
+      export namespace RecipientAgent {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: 'agent';
+        }
+      }
+
+      /**
+       * Party that initiated the payment
+       */
+      export interface Sender {
+        /**
+         * Related resource identifier
+         */
+        data: Sender.Data;
+      }
+
+      export namespace Sender {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: 'party';
+        }
+      }
+
+      /**
+       * Sender-side transaction row for this payment, when available.
+       */
+      export interface Transaction {
+        /**
+         * Related resource identifier
+         */
+        data: Transaction.Data | null;
+      }
+
+      export namespace Transaction {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: 'transaction';
+        }
+      }
     }
   }
 }
@@ -864,7 +1132,7 @@ export namespace PaymentRequestGetResponse {
     /**
      * Resource type
      */
-    type: string;
+    type: 'paymentRequest';
   }
 
   export namespace Data {
@@ -940,7 +1208,15 @@ export namespace PaymentRequestGetResponse {
       /**
        * Current status of the payment request
        */
-      status: 'OPEN' | 'PROCESSING' | 'COMPLETED' | 'CANCELLED' | 'DECLINED' | 'EXPIRED';
+      status:
+        | 'OPEN'
+        | 'PROCESSING'
+        | 'COMPLETED'
+        | 'FAILED'
+        | 'RETURNED'
+        | 'CANCELLED'
+        | 'DECLINED'
+        | 'EXPIRED';
 
       /**
        * ID of the transaction created by the most recent payment attempt, or null if no
@@ -963,6 +1239,11 @@ export namespace PaymentRequestGetResponse {
        */
       payerParty: Relationships.PayerParty;
 
+      /**
+       * Payment submitted for this payment request, if one exists.
+       */
+      payment: Relationships.Payment;
+
       /**
        * Party requesting the payment
        */
@@ -995,7 +1276,31 @@ export namespace PaymentRequestGetResponse {
           /**
            * Resource type
            */
-          type: string;
+          type: 'party';
+        }
+      }
+
+      /**
+       * Payment submitted for this payment request, if one exists.
+       */
+      export interface Payment {
+        /**
+         * Related resource identifier
+         */
+        data: Payment.Data | null;
+      }
+
+      export namespace Payment {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: 'payment';
         }
       }
 
@@ -1019,7 +1324,7 @@ export namespace PaymentRequestGetResponse {
           /**
            * Resource type
            */
-          type: string;
+          type: 'party';
         }
       }
 
@@ -1043,7 +1348,7 @@ export namespace PaymentRequestGetResponse {
           /**
            * Resource type
            */
-          type: string;
+          type: 'wallet';
         }
       }
     }
@@ -1076,7 +1381,7 @@ export namespace PaymentRequestListIncomingResponse {
     /**
      * Resource type
      */
-    type: string;
+    type: 'paymentRequest';
   }
 
   export namespace Data {
@@ -1152,7 +1457,15 @@ export namespace PaymentRequestListIncomingResponse {
       /**
        * Current status of the payment request
        */
-      status: 'OPEN' | 'PROCESSING' | 'COMPLETED' | 'CANCELLED' | 'DECLINED' | 'EXPIRED';
+      status:
+        | 'OPEN'
+        | 'PROCESSING'
+        | 'COMPLETED'
+        | 'FAILED'
+        | 'RETURNED'
+        | 'CANCELLED'
+        | 'DECLINED'
+        | 'EXPIRED';
 
       /**
        * ID of the transaction created by the most recent payment attempt, or null if no
@@ -1175,6 +1488,11 @@ export namespace PaymentRequestListIncomingResponse {
        */
       payerParty: Relationships.PayerParty;
 
+      /**
+       * Payment submitted for this payment request, if one exists.
+       */
+      payment: Relationships.Payment;
+
       /**
        * Party requesting the payment
        */
@@ -1207,7 +1525,31 @@ export namespace PaymentRequestListIncomingResponse {
           /**
            * Resource type
            */
-          type: string;
+          type: 'party';
+        }
+      }
+
+      /**
+       * Payment submitted for this payment request, if one exists.
+       */
+      export interface Payment {
+        /**
+         * Related resource identifier
+         */
+        data: Payment.Data | null;
+      }
+
+      export namespace Payment {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: 'payment';
         }
       }
 
@@ -1231,7 +1573,7 @@ export namespace PaymentRequestListIncomingResponse {
           /**
            * Resource type
            */
-          type: string;
+          type: 'party';
         }
       }
 
@@ -1255,7 +1597,7 @@ export namespace PaymentRequestListIncomingResponse {
           /**
            * Resource type
            */
-          type: string;
+          type: 'wallet';
         }
       }
     }
@@ -1284,7 +1626,11 @@ export interface PaymentRequestCreateParams {
    * Body param: Who pays — exactly one typed email, phone, party ID, or agent ID
    * value.
    */
-  payer: PaymentRequestCreateParams.UnionMember0 | PaymentRequestCreateParams.UnionMember1;
+  payer:
+    | PaymentRequestCreateParams.UnionMember0
+    | PaymentRequestCreateParams.UnionMember1
+    | PaymentRequestCreateParams.UnionMember2
+    | PaymentRequestCreateParams.UnionMember3;
 
   /**
    * Header param: Unique key for idempotent request handling. If a request with the
@@ -1292,6 +1638,16 @@ export interface PaymentRequestCreateParams {
    */
   'Idempotency-Key': string;
 
+  /**
+   * Header param: Agent ID (agt_xxx) used for attribution and audit.
+   */
+  'X-Agent-ID': string;
+
+  /**
+   * Header param: Stable run, session, or conversation ID for agent observability.
+   */
+  'X-Instance-ID': string;
+
   /**
    * Body param: Currency code (currently only USD)
    */
@@ -1324,22 +1680,11 @@ export interface PaymentRequestCreateParams {
    * party's default wallet.
    */
   walletId?: string;
-
-  /**
-   * Header param: Agent ID (agt_xxx) identifying which agent is making the request.
-   */
-  'X-Agent-ID'?: string;
-
-  /**
-   * Header param: Required when X-Agent-ID is present. Session or conversation ID
-   * for agent observability.
-   */
-  'X-Instance-ID'?: string;
 }
 
 export namespace PaymentRequestCreateParams {
   export interface UnionMember0 {
-    type: string;
+    type: 'email';
 
     /**
      * Email address
@@ -1348,7 +1693,7 @@ export namespace PaymentRequestCreateParams {
   }
 
   export interface UnionMember1 {
-    type: string;
+    type: 'phone';
 
     /**
      * Phone number in E.164 format
@@ -1356,6 +1701,24 @@ export namespace PaymentRequestCreateParams {
     value: string;
   }
 
+  export interface UnionMember2 {
+    type: 'party_id';
+
+    /**
+     * Natural party ID (pty\_\*)
+     */
+    value: string;
+  }
+
+  export interface UnionMember3 {
+    type: 'agent_id';
+
+    /**
+     * Natural agent ID (agt\_\*)
+     */
+    value: string;
+  }
+
   /**
    * If provided, immediately deliver the payment link to the payer via the named
    * channel
@@ -1370,25 +1733,24 @@ export namespace PaymentRequestCreateParams {
 
 export interface PaymentRequestListParams {
   /**
-   * Query param: Pagination cursor returned by the previous response
+   * Header param: Agent ID (agt_xxx) used for attribution and audit.
    */
-  cursor?: string;
+  'X-Agent-ID': string;
 
   /**
-   * Query param: Results per page (1-100)
+   * Header param: Stable run, session, or conversation ID for agent observability.
    */
-  limit?: number;
+  'X-Instance-ID': string;
 
   /**
-   * Header param: Agent ID (agt_xxx) identifying which agent is making the request.
+   * Query param: Pagination cursor returned by the previous response
    */
-  'X-Agent-ID'?: string;
+  cursor?: string;
 
   /**
-   * Header param: Required when X-Agent-ID is present. Session or conversation ID
-   * for agent observability.
+   * Query param: Results per page (1-100)
    */
-  'X-Instance-ID'?: string;
+  limit?: number;
 }
 
 export interface PaymentRequestDeclineParams {
@@ -1399,15 +1761,14 @@ export interface PaymentRequestDeclineParams {
   'Idempotency-Key': string;
 
   /**
-   * Agent ID (agt_xxx) identifying which agent is making the request.
+   * Agent ID (agt_xxx) used for attribution and audit.
    */
-  'X-Agent-ID'?: string;
+  'X-Agent-ID': string;
 
   /**
-   * Required when X-Agent-ID is present. Session or conversation ID for agent
-   * observability.
+   * Stable run, session, or conversation ID for agent observability.
    */
-  'X-Instance-ID'?: string;
+  'X-Instance-ID': string;
 }
 
 export interface PaymentRequestFulfillParams {
@@ -1423,20 +1784,19 @@ export interface PaymentRequestFulfillParams {
   'Idempotency-Key': string;
 
   /**
-   * Header param: Agent ID (agt_xxx) identifying which agent is making the request.
+   * Header param: Agent ID (agt_xxx) used for attribution and audit.
    */
-  'X-Agent-ID'?: string;
+  'X-Agent-ID': string;
 
   /**
-   * Header param: Required when X-Agent-ID is present. Session or conversation ID
-   * for agent observability.
+   * Header param: Stable run, session, or conversation ID for agent observability.
    */
-  'X-Instance-ID'?: string;
+  'X-Instance-ID': string;
 }
 
 export namespace PaymentRequestFulfillParams {
   export interface UnionMember0 {
-    type: string;
+    type: 'wallet';
 
     walletId: string;
   }
@@ -1444,44 +1804,42 @@ export namespace PaymentRequestFulfillParams {
   export interface UnionMember1 {
     externalAccountId: string;
 
-    type: string;
+    type: 'external_account';
   }
 }
 
 export interface PaymentRequestGetParams {
   /**
-   * Agent ID (agt_xxx) identifying which agent is making the request.
+   * Agent ID (agt_xxx) used for attribution and audit.
    */
-  'X-Agent-ID'?: string;
+  'X-Agent-ID': string;
 
   /**
-   * Required when X-Agent-ID is present. Session or conversation ID for agent
-   * observability.
+   * Stable run, session, or conversation ID for agent observability.
    */
-  'X-Instance-ID'?: string;
+  'X-Instance-ID': string;
 }
 
 export interface PaymentRequestListIncomingParams {
   /**
-   * Query param: Pagination cursor returned by the previous response
+   * Header param: Agent ID (agt_xxx) used for attribution and audit.
    */
-  cursor?: string;
+  'X-Agent-ID': string;
 
   /**
-   * Query param: Results per page (1-100)
+   * Header param: Stable run, session, or conversation ID for agent observability.
    */
-  limit?: number;
+  'X-Instance-ID': string;
 
   /**
-   * Header param: Agent ID (agt_xxx) identifying which agent is making the request.
+   * Query param: Pagination cursor returned by the previous response
    */
-  'X-Agent-ID'?: string;
+  cursor?: string;
 
   /**
-   * Header param: Required when X-Agent-ID is present. Session or conversation ID
-   * for agent observability.
+   * Query param: Results per page (1-100)
    */
-  'X-Instance-ID'?: string;
+  limit?: number;
 }
 
 export declare namespace PaymentRequests {