@naturalpay/sdk 0.3.0 → 0.4.0

package/src/resources/payment-requests.ts

@@ -17,7 +17,7 @@ export class PaymentRequests extends APIResource {
    * ```ts
    * const paymentRequest = await client.paymentRequests.create({
    *   amount: 1,
-   *   payer: { kind: 'email', value: 'dev@stainless.com' },
+   *   payer: { type: 'type', value: 'dev@stainless.com' },
    *   'Idempotency-Key': 'Idempotency-Key',
    * });
    * ```
@@ -72,6 +72,83 @@ export class PaymentRequests extends APIResource {
     });
   }
 
+  /**
+   * Decline an open payment request where the authenticated party is expected to
+   * pay.
+   *
+   * @example
+   * ```ts
+   * const response = await client.paymentRequests.decline(
+   *   'prq_ecc2efdd09bd231a9ad9bd2aada37aa7',
+   *   { 'Idempotency-Key': 'Idempotency-Key' },
+   * );
+   * ```
+   */
+  decline(
+    paymentRequestID: string,
+    params: PaymentRequestDeclineParams,
+    options?: RequestOptions,
+  ): APIPromise<PaymentRequestDeclineResponse> {
+    const {
+      'Idempotency-Key': idempotencyKey,
+      'X-Agent-ID': xAgentID,
+      'X-Instance-ID': xInstanceID,
+    } = params;
+    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),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Fulfill an open payment request from inside the authenticated app.
+   *
+   * @example
+   * ```ts
+   * const response = await client.paymentRequests.fulfill(
+   *   'prq_ecc2efdd09bd231a9ad9bd2aada37aa7',
+   *   {
+   *     paymentSource: {
+   *       type: 'type',
+   *       walletId: 'wal_ecc2efdd09bd231a9ad9bd2aada37aa7',
+   *     },
+   *     'Idempotency-Key': 'Idempotency-Key',
+   *   },
+   * );
+   * ```
+   */
+  fulfill(
+    paymentRequestID: string,
+    params: PaymentRequestFulfillParams,
+    options?: RequestOptions,
+  ): APIPromise<PaymentRequestFulfillResponse> {
+    const {
+      'Idempotency-Key': idempotencyKey,
+      'X-Agent-ID': xAgentID,
+      'X-Instance-ID': xInstanceID,
+      ...body
+    } = params;
+    return this._client.post(path`/payment-requests/${paymentRequestID}/fulfill`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          'Idempotency-Key': idempotencyKey,
+          ...(xAgentID != null ? { 'X-Agent-ID': xAgentID } : undefined),
+          ...(xInstanceID != null ? { 'X-Instance-ID': xInstanceID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
   /**
    * Get a single payment request visible to the authenticated requester party.
    *
@@ -99,13 +176,445 @@ export class PaymentRequests extends APIResource {
       ]),
     });
   }
+
+  /**
+   * List open payment requests where the authenticated party is expected to pay.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.paymentRequests.listIncoming();
+   * ```
+   */
+  listIncoming(
+    params: PaymentRequestListIncomingParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<PaymentRequestListIncomingResponse> {
+    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,
+      ]),
+    });
+  }
+}
+
+export interface PaymentRequestCreateResponse {
+  data: PaymentRequestCreateResponse.Data;
+}
+
+export namespace PaymentRequestCreateResponse {
+  export interface Data {
+    /**
+     * Resource ID (prq\_\*)
+     */
+    id: string;
+
+    /**
+     * Resource attributes
+     */
+    attributes: Data.Attributes;
+
+    /**
+     * Resource relationships
+     */
+    relationships: Data.Relationships;
+
+    /**
+     * Resource type
+     */
+    type: string;
+  }
+
+  export namespace Data {
+    /**
+     * Resource attributes
+     */
+    export interface Attributes {
+      /**
+       * Amount in cents
+       */
+      amount: number;
+
+      /**
+       * ISO 8601 timestamp when the payment request was created
+       */
+      createdAt: string;
+
+      /**
+       * Currency code
+       */
+      currency: string;
+
+      /**
+       * Free-form description provided at creation. Maximum 500 characters.
+       */
+      description: string | null;
+
+      /**
+       * Email of the payer if addressed by email
+       */
+      payerEmail: string | null;
+
+      /**
+       * The identifier value used to address the payer
+       */
+      payerIdentifier: string;
+
+      /**
+       * Which identifier type was used to address the payer
+       */
+      payerIdentifierType: 'email' | 'phone' | 'party_id' | 'agent_id';
+
+      /**
+       * Display name of the payer
+       */
+      payerName: string | null;
+
+      /**
+       * Natural party ID (pty\_\*) resolved for the payer, including agent owner parties
+       */
+      payerPartyId: string | null;
+
+      /**
+       * Phone of the payer in E.164 format if addressed by phone
+       */
+      payerPhone: string | null;
+
+      /**
+       * URL the payer visits to complete payment
+       */
+      paymentLinkUrl: string;
+
+      /**
+       * Email of the party requesting payment
+       */
+      requesterEmail: string | null;
+
+      /**
+       * Display name of the party requesting payment
+       */
+      requesterName: string | null;
+
+      /**
+       * Current status of the payment request
+       */
+      status: 'OPEN' | 'PROCESSING' | 'COMPLETED' | 'CANCELLED' | 'DECLINED' | 'EXPIRED';
+
+      /**
+       * ID of the transaction created by the most recent payment attempt, or null if no
+       * attempt yet
+       */
+      transactionId: string | null;
+
+      /**
+       * ISO 8601 timestamp when the payment request was last updated
+       */
+      updatedAt: string;
+    }
+
+    /**
+     * Resource relationships
+     */
+    export interface Relationships {
+      /**
+       * Resolved payer party, if the payer is known to Natural
+       */
+      payerParty: Relationships.PayerParty;
+
+      /**
+       * Party requesting the payment
+       */
+      requesterParty: Relationships.RequesterParty;
+    }
+
+    export namespace Relationships {
+      /**
+       * Resolved payer party, if the payer is known to Natural
+       */
+      export interface PayerParty {
+        /**
+         * Related resource identifier
+         */
+        data: PayerParty.Data | null;
+      }
+
+      export namespace PayerParty {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+
+      /**
+       * Party requesting the payment
+       */
+      export interface RequesterParty {
+        /**
+         * Related resource identifier
+         */
+        data: RequesterParty.Data;
+      }
+
+      export namespace RequesterParty {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+    }
+  }
+}
+
+export interface PaymentRequestListResponse {
+  data: Array<PaymentRequestListResponse.Data>;
+
+  meta: PaymentRequestListResponse.Meta;
+}
+
+export namespace PaymentRequestListResponse {
+  export interface Data {
+    /**
+     * Resource ID (prq\_\*)
+     */
+    id: string;
+
+    /**
+     * Resource attributes
+     */
+    attributes: Data.Attributes;
+
+    /**
+     * Resource relationships
+     */
+    relationships: Data.Relationships;
+
+    /**
+     * Resource type
+     */
+    type: string;
+  }
+
+  export namespace Data {
+    /**
+     * Resource attributes
+     */
+    export interface Attributes {
+      /**
+       * Amount in cents
+       */
+      amount: number;
+
+      /**
+       * ISO 8601 timestamp when the payment request was created
+       */
+      createdAt: string;
+
+      /**
+       * Currency code
+       */
+      currency: string;
+
+      /**
+       * Free-form description provided at creation. Maximum 500 characters.
+       */
+      description: string | null;
+
+      /**
+       * Email of the payer if addressed by email
+       */
+      payerEmail: string | null;
+
+      /**
+       * The identifier value used to address the payer
+       */
+      payerIdentifier: string;
+
+      /**
+       * Which identifier type was used to address the payer
+       */
+      payerIdentifierType: 'email' | 'phone' | 'party_id' | 'agent_id';
+
+      /**
+       * Display name of the payer
+       */
+      payerName: string | null;
+
+      /**
+       * Natural party ID (pty\_\*) resolved for the payer, including agent owner parties
+       */
+      payerPartyId: string | null;
+
+      /**
+       * Phone of the payer in E.164 format if addressed by phone
+       */
+      payerPhone: string | null;
+
+      /**
+       * URL the payer visits to complete payment
+       */
+      paymentLinkUrl: string;
+
+      /**
+       * Email of the party requesting payment
+       */
+      requesterEmail: string | null;
+
+      /**
+       * Display name of the party requesting payment
+       */
+      requesterName: string | null;
+
+      /**
+       * Current status of the payment request
+       */
+      status: 'OPEN' | 'PROCESSING' | 'COMPLETED' | 'CANCELLED' | 'DECLINED' | 'EXPIRED';
+
+      /**
+       * ID of the transaction created by the most recent payment attempt, or null if no
+       * attempt yet
+       */
+      transactionId: string | null;
+
+      /**
+       * ISO 8601 timestamp when the payment request was last updated
+       */
+      updatedAt: string;
+    }
+
+    /**
+     * Resource relationships
+     */
+    export interface Relationships {
+      /**
+       * Resolved payer party, if the payer is known to Natural
+       */
+      payerParty: Relationships.PayerParty;
+
+      /**
+       * Party requesting the payment
+       */
+      requesterParty: Relationships.RequesterParty;
+
+      /**
+       * Wallet that receives the funds
+       */
+      wallet: Relationships.Wallet;
+    }
+
+    export namespace Relationships {
+      /**
+       * Resolved payer party, if the payer is known to Natural
+       */
+      export interface PayerParty {
+        /**
+         * Related resource identifier
+         */
+        data: PayerParty.Data | null;
+      }
+
+      export namespace PayerParty {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+
+      /**
+       * Party requesting the payment
+       */
+      export interface RequesterParty {
+        /**
+         * Related resource identifier
+         */
+        data: RequesterParty.Data;
+      }
+
+      export namespace RequesterParty {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+
+      /**
+       * Wallet that receives the funds
+       */
+      export interface Wallet {
+        /**
+         * Related resource identifier
+         */
+        data: Wallet.Data;
+      }
+
+      export namespace Wallet {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+    }
+  }
+
+  export interface Meta {
+    pagination: Meta.Pagination;
+  }
+
+  export namespace Meta {
+    export interface Pagination {
+      hasMore: boolean;
+
+      nextCursor: string | null;
+    }
+  }
 }
 
-export interface PaymentRequestCreateResponse {
-  data: PaymentRequestCreateResponse.Data;
+export interface PaymentRequestDeclineResponse {
+  data: PaymentRequestDeclineResponse.Data;
 }
 
-export namespace PaymentRequestCreateResponse {
+export namespace PaymentRequestDeclineResponse {
   export interface Data {
     /**
      * Resource ID (prq\_\*)
@@ -117,6 +626,11 @@ export namespace PaymentRequestCreateResponse {
      */
     attributes: Data.Attributes;
 
+    /**
+     * Resource relationships
+     */
+    relationships: Data.Relationships;
+
     /**
      * Resource type
      */
@@ -144,7 +658,7 @@ export namespace PaymentRequestCreateResponse {
       currency: string;
 
       /**
-       * Free-form description provided at creation
+       * Free-form description provided at creation. Maximum 500 characters.
        */
       description: string | null;
 
@@ -184,12 +698,12 @@ export namespace PaymentRequestCreateResponse {
       paymentLinkUrl: string;
 
       /**
-       * Email of the requester party
+       * Email of the party requesting payment
        */
       requesterEmail: string | null;
 
       /**
-       * Display name of the requester party
+       * Display name of the party requesting payment
        */
       requesterName: string | null;
 
@@ -209,16 +723,128 @@ export namespace PaymentRequestCreateResponse {
        */
       updatedAt: string;
     }
+
+    /**
+     * Resource relationships
+     */
+    export interface Relationships {
+      /**
+       * Resolved payer party, if the payer is known to Natural
+       */
+      payerParty: Relationships.PayerParty;
+
+      /**
+       * Party requesting the payment
+       */
+      requesterParty: Relationships.RequesterParty;
+
+      /**
+       * Wallet that receives the funds
+       */
+      wallet: Relationships.Wallet;
+    }
+
+    export namespace Relationships {
+      /**
+       * Resolved payer party, if the payer is known to Natural
+       */
+      export interface PayerParty {
+        /**
+         * Related resource identifier
+         */
+        data: PayerParty.Data | null;
+      }
+
+      export namespace PayerParty {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+
+      /**
+       * Party requesting the payment
+       */
+      export interface RequesterParty {
+        /**
+         * Related resource identifier
+         */
+        data: RequesterParty.Data;
+      }
+
+      export namespace RequesterParty {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+
+      /**
+       * Wallet that receives the funds
+       */
+      export interface Wallet {
+        /**
+         * Related resource identifier
+         */
+        data: Wallet.Data;
+      }
+
+      export namespace Wallet {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+    }
   }
 }
 
-export interface PaymentRequestListResponse {
-  data: Array<PaymentRequestListResponse.Data>;
+export interface PaymentRequestFulfillResponse {
+  data: PaymentRequestFulfillResponse.Data;
+}
 
-  meta: PaymentRequestListResponse.Meta;
+export namespace PaymentRequestFulfillResponse {
+  export interface Data {
+    id: string;
+
+    attributes: Data.Attributes;
+
+    type: string;
+  }
+
+  export namespace Data {
+    export interface Attributes {
+      outcome: 'processing' | 'failed' | 'completed' | 'in_review';
+    }
+  }
 }
 
-export namespace PaymentRequestListResponse {
+export interface PaymentRequestGetResponse {
+  data: PaymentRequestGetResponse.Data;
+}
+
+export namespace PaymentRequestGetResponse {
   export interface Data {
     /**
      * Resource ID (prq\_\*)
@@ -230,6 +856,11 @@ export namespace PaymentRequestListResponse {
      */
     attributes: Data.Attributes;
 
+    /**
+     * Resource relationships
+     */
+    relationships: Data.Relationships;
+
     /**
      * Resource type
      */
@@ -257,7 +888,7 @@ export namespace PaymentRequestListResponse {
       currency: string;
 
       /**
-       * Free-form description provided at creation
+       * Free-form description provided at creation. Maximum 500 characters.
        */
       description: string | null;
 
@@ -297,12 +928,12 @@ export namespace PaymentRequestListResponse {
       paymentLinkUrl: string;
 
       /**
-       * Email of the requester party
+       * Email of the party requesting payment
        */
       requesterEmail: string | null;
 
       /**
-       * Display name of the requester party
+       * Display name of the party requesting payment
        */
       requesterName: string | null;
 
@@ -322,26 +953,110 @@ export namespace PaymentRequestListResponse {
        */
       updatedAt: string;
     }
-  }
 
-  export interface Meta {
-    pagination: Meta.Pagination;
-  }
+    /**
+     * Resource relationships
+     */
+    export interface Relationships {
+      /**
+       * Resolved payer party, if the payer is known to Natural
+       */
+      payerParty: Relationships.PayerParty;
 
-  export namespace Meta {
-    export interface Pagination {
-      hasMore: boolean;
+      /**
+       * Party requesting the payment
+       */
+      requesterParty: Relationships.RequesterParty;
 
-      nextCursor: string | null;
+      /**
+       * Wallet that receives the funds
+       */
+      wallet: Relationships.Wallet;
+    }
+
+    export namespace Relationships {
+      /**
+       * Resolved payer party, if the payer is known to Natural
+       */
+      export interface PayerParty {
+        /**
+         * Related resource identifier
+         */
+        data: PayerParty.Data | null;
+      }
+
+      export namespace PayerParty {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+
+      /**
+       * Party requesting the payment
+       */
+      export interface RequesterParty {
+        /**
+         * Related resource identifier
+         */
+        data: RequesterParty.Data;
+      }
+
+      export namespace RequesterParty {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+
+      /**
+       * Wallet that receives the funds
+       */
+      export interface Wallet {
+        /**
+         * Related resource identifier
+         */
+        data: Wallet.Data;
+      }
+
+      export namespace Wallet {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
     }
   }
 }
 
-export interface PaymentRequestGetResponse {
-  data: PaymentRequestGetResponse.Data;
+export interface PaymentRequestListIncomingResponse {
+  data: Array<PaymentRequestListIncomingResponse.Data>;
+
+  meta: PaymentRequestListIncomingResponse.Meta;
 }
 
-export namespace PaymentRequestGetResponse {
+export namespace PaymentRequestListIncomingResponse {
   export interface Data {
     /**
      * Resource ID (prq\_\*)
@@ -353,6 +1068,11 @@ export namespace PaymentRequestGetResponse {
      */
     attributes: Data.Attributes;
 
+    /**
+     * Resource relationships
+     */
+    relationships: Data.Relationships;
+
     /**
      * Resource type
      */
@@ -380,7 +1100,7 @@ export namespace PaymentRequestGetResponse {
       currency: string;
 
       /**
-       * Free-form description provided at creation
+       * Free-form description provided at creation. Maximum 500 characters.
        */
       description: string | null;
 
@@ -420,12 +1140,12 @@ export namespace PaymentRequestGetResponse {
       paymentLinkUrl: string;
 
       /**
-       * Email of the requester party
+       * Email of the party requesting payment
        */
       requesterEmail: string | null;
 
       /**
-       * Display name of the requester party
+       * Display name of the party requesting payment
        */
       requesterName: string | null;
 
@@ -445,23 +1165,126 @@ export namespace PaymentRequestGetResponse {
        */
       updatedAt: string;
     }
+
+    /**
+     * Resource relationships
+     */
+    export interface Relationships {
+      /**
+       * Resolved payer party, if the payer is known to Natural
+       */
+      payerParty: Relationships.PayerParty;
+
+      /**
+       * Party requesting the payment
+       */
+      requesterParty: Relationships.RequesterParty;
+
+      /**
+       * Wallet that receives the funds
+       */
+      wallet: Relationships.Wallet;
+    }
+
+    export namespace Relationships {
+      /**
+       * Resolved payer party, if the payer is known to Natural
+       */
+      export interface PayerParty {
+        /**
+         * Related resource identifier
+         */
+        data: PayerParty.Data | null;
+      }
+
+      export namespace PayerParty {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+
+      /**
+       * Party requesting the payment
+       */
+      export interface RequesterParty {
+        /**
+         * Related resource identifier
+         */
+        data: RequesterParty.Data;
+      }
+
+      export namespace RequesterParty {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+
+      /**
+       * Wallet that receives the funds
+       */
+      export interface Wallet {
+        /**
+         * Related resource identifier
+         */
+        data: Wallet.Data;
+      }
+
+      export namespace Wallet {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: string;
+        }
+      }
+    }
+  }
+
+  export interface Meta {
+    pagination: Meta.Pagination;
+  }
+
+  export namespace Meta {
+    export interface Pagination {
+      hasMore: boolean;
+
+      nextCursor: string | null;
+    }
   }
 }
 
 export interface PaymentRequestCreateParams {
   /**
-   * Body param: Amount in cents
+   * Body param: Amount in minor units (cents for USD)
    */
   amount: number;
 
   /**
-   * Body param: Who pays — exactly one of email, phone, party, or agent.
+   * Body param: Who pays — exactly one typed email, phone, party ID, or agent ID
+   * value.
    */
-  payer:
-    | PaymentRequestCreateParams.UnionMember0
-    | PaymentRequestCreateParams.UnionMember1
-    | PaymentRequestCreateParams.UnionMember2
-    | PaymentRequestCreateParams.UnionMember3;
+  payer: PaymentRequestCreateParams.UnionMember0 | PaymentRequestCreateParams.UnionMember1;
 
   /**
    * Header param: Unique key for idempotent request handling. If a request with the
@@ -481,7 +1304,7 @@ export interface PaymentRequestCreateParams {
   customerPartyId?: string;
 
   /**
-   * Body param: Free-form description shown to the payer
+   * Body param: Free-form description shown to the payer. Maximum 500 characters.
    */
   description?: string;
 
@@ -516,37 +1339,19 @@ export interface PaymentRequestCreateParams {
 
 export namespace PaymentRequestCreateParams {
   export interface UnionMember0 {
-    kind: 'email';
+    type: string;
 
     /**
-     * Payer email address
+     * Email address
      */
     value: string;
   }
 
   export interface UnionMember1 {
-    kind: 'phone';
-
-    /**
-     * Payer phone in E.164 format
-     */
-    value: string;
-  }
-
-  export interface UnionMember2 {
-    kind: 'party_id';
-
-    /**
-     * Natural party ID (pty\_\*) of the payer
-     */
-    value: string;
-  }
-
-  export interface UnionMember3 {
-    kind: 'agent_id';
+    type: string;
 
     /**
-     * Natural agent ID (agt\_\*) of the payer
+     * Phone number in E.164 format
      */
     value: string;
   }
@@ -586,6 +1391,63 @@ export interface PaymentRequestListParams {
   'X-Instance-ID'?: string;
 }
 
+export interface PaymentRequestDeclineParams {
+  /**
+   * Unique key for idempotent request handling. If a request with the same key was
+   * already processed, the original response is returned.
+   */
+  'Idempotency-Key': string;
+
+  /**
+   * Agent ID (agt_xxx) identifying which agent is making the request.
+   */
+  'X-Agent-ID'?: string;
+
+  /**
+   * Required when X-Agent-ID is present. Session or conversation ID for agent
+   * observability.
+   */
+  'X-Instance-ID'?: string;
+}
+
+export interface PaymentRequestFulfillParams {
+  /**
+   * Body param
+   */
+  paymentSource: PaymentRequestFulfillParams.UnionMember0 | PaymentRequestFulfillParams.UnionMember1;
+
+  /**
+   * Header param: Unique key for idempotent request handling. If a request with the
+   * same key was already processed, the original response is returned.
+   */
+  'Idempotency-Key': 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 PaymentRequestFulfillParams {
+  export interface UnionMember0 {
+    type: string;
+
+    walletId: string;
+  }
+
+  export interface UnionMember1 {
+    externalAccountId: string;
+
+    type: string;
+  }
+}
+
 export interface PaymentRequestGetParams {
   /**
    * Agent ID (agt_xxx) identifying which agent is making the request.
@@ -599,13 +1461,42 @@ export interface PaymentRequestGetParams {
   'X-Instance-ID'?: string;
 }
 
+export interface PaymentRequestListIncomingParams {
+  /**
+   * Query param: Pagination cursor returned by the previous response
+   */
+  cursor?: string;
+
+  /**
+   * Query param: Results per page (1-100)
+   */
+  limit?: number;
+
+  /**
+   * 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 declare namespace PaymentRequests {
   export {
     type PaymentRequestCreateResponse as PaymentRequestCreateResponse,
     type PaymentRequestListResponse as PaymentRequestListResponse,
+    type PaymentRequestDeclineResponse as PaymentRequestDeclineResponse,
+    type PaymentRequestFulfillResponse as PaymentRequestFulfillResponse,
     type PaymentRequestGetResponse as PaymentRequestGetResponse,
+    type PaymentRequestListIncomingResponse as PaymentRequestListIncomingResponse,
     type PaymentRequestCreateParams as PaymentRequestCreateParams,
     type PaymentRequestListParams as PaymentRequestListParams,
+    type PaymentRequestDeclineParams as PaymentRequestDeclineParams,
+    type PaymentRequestFulfillParams as PaymentRequestFulfillParams,
     type PaymentRequestGetParams as PaymentRequestGetParams,
+    type PaymentRequestListIncomingParams as PaymentRequestListIncomingParams,
   };
 }