@naturalpay/sdk 0.9.0 → 0.11.0

package/resources/payment-requests.d.ts

@@ -12,8 +12,10 @@ export declare 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',
      * });
      * ```
      */
@@ -23,10 +25,13 @@ export declare 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>;
+    list(params: PaymentRequestListParams, options?: RequestOptions): APIPromise<PaymentRequestListResponse>;
     /**
      * Decline an open payment request where the authenticated party is expected to
      * pay.
@@ -35,7 +40,11 @@ export declare 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',
+     *   },
      * );
      * ```
      */
@@ -49,10 +58,12 @@ export declare 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',
      *   },
      * );
      * ```
@@ -65,20 +76,26 @@ export declare 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, options?: RequestOptions): APIPromise<PaymentRequestGetResponse>;
+    get(paymentRequestID: string, params: PaymentRequestGetParams, options?: RequestOptions): APIPromise<PaymentRequestGetResponse>;
     /**
      * List open payment requests where the authenticated party is expected to pay.
      *
      * @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, options?: RequestOptions): APIPromise<PaymentRequestListIncomingResponse>;
+    listIncoming(params: PaymentRequestListIncomingParams, options?: RequestOptions): APIPromise<PaymentRequestListIncomingResponse>;
 }
 export interface PaymentRequestCreateResponse {
     data: PaymentRequestCreateResponse.Data;
@@ -100,7 +117,7 @@ export declare namespace PaymentRequestCreateResponse {
         /**
          * Resource type
          */
-        type: string;
+        type: 'paymentRequest';
     }
     namespace Data {
         /**
@@ -162,7 +179,7 @@ export declare 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
              * attempt yet
@@ -205,7 +222,7 @@ export declare namespace PaymentRequestCreateResponse {
                     /**
                      * Resource type
                      */
-                    type: string;
+                    type: 'party';
                 }
             }
             /**
@@ -226,7 +243,7 @@ export declare namespace PaymentRequestCreateResponse {
                     /**
                      * Resource type
                      */
-                    type: string;
+                    type: 'party';
                 }
             }
         }
@@ -253,7 +270,7 @@ export declare namespace PaymentRequestListResponse {
         /**
          * Resource type
          */
-        type: string;
+        type: 'paymentRequest';
     }
     namespace Data {
         /**
@@ -315,7 +332,7 @@ export declare 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
              * attempt yet
@@ -334,6 +351,10 @@ export declare namespace PaymentRequestListResponse {
              * Resolved payer party, if the payer is known to Natural
              */
             payerParty: Relationships.PayerParty;
+            /**
+             * Payment submitted for this payment request, if one exists.
+             */
+            payment: Relationships.Payment;
             /**
              * Party requesting the payment
              */
@@ -362,7 +383,28 @@ export declare namespace PaymentRequestListResponse {
                     /**
                      * Resource type
                      */
-                    type: string;
+                    type: 'party';
+                }
+            }
+            /**
+             * Payment submitted for this payment request, if one exists.
+             */
+            interface Payment {
+                /**
+                 * Related resource identifier
+                 */
+                data: Payment.Data | null;
+            }
+            namespace Payment {
+                /**
+                 * Related resource identifier
+                 */
+                interface Data {
+                    id: string;
+                    /**
+                     * Resource type
+                     */
+                    type: 'payment';
                 }
             }
             /**
@@ -383,7 +425,7 @@ export declare namespace PaymentRequestListResponse {
                     /**
                      * Resource type
                      */
-                    type: string;
+                    type: 'party';
                 }
             }
             /**
@@ -404,7 +446,7 @@ export declare namespace PaymentRequestListResponse {
                     /**
                      * Resource type
                      */
-                    type: string;
+                    type: 'wallet';
                 }
             }
         }
@@ -439,7 +481,7 @@ export declare namespace PaymentRequestDeclineResponse {
         /**
          * Resource type
          */
-        type: string;
+        type: 'paymentRequest';
     }
     namespace Data {
         /**
@@ -501,7 +543,7 @@ export declare 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
              * attempt yet
@@ -520,6 +562,10 @@ export declare namespace PaymentRequestDeclineResponse {
              * Resolved payer party, if the payer is known to Natural
              */
             payerParty: Relationships.PayerParty;
+            /**
+             * Payment submitted for this payment request, if one exists.
+             */
+            payment: Relationships.Payment;
             /**
              * Party requesting the payment
              */
@@ -548,7 +594,28 @@ export declare namespace PaymentRequestDeclineResponse {
                     /**
                      * Resource type
                      */
-                    type: string;
+                    type: 'party';
+                }
+            }
+            /**
+             * Payment submitted for this payment request, if one exists.
+             */
+            interface Payment {
+                /**
+                 * Related resource identifier
+                 */
+                data: Payment.Data | null;
+            }
+            namespace Payment {
+                /**
+                 * Related resource identifier
+                 */
+                interface Data {
+                    id: string;
+                    /**
+                     * Resource type
+                     */
+                    type: 'payment';
                 }
             }
             /**
@@ -569,7 +636,7 @@ export declare namespace PaymentRequestDeclineResponse {
                     /**
                      * Resource type
                      */
-                    type: string;
+                    type: 'party';
                 }
             }
             /**
@@ -590,7 +657,7 @@ export declare namespace PaymentRequestDeclineResponse {
                     /**
                      * Resource type
                      */
-                    type: string;
+                    type: 'wallet';
                 }
             }
         }
@@ -602,12 +669,179 @@ export interface PaymentRequestFulfillResponse {
 export declare namespace PaymentRequestFulfillResponse {
     interface Data {
         id: string;
+        /**
+         * Resource attributes
+         */
         attributes: Data.Attributes;
-        type: string;
+        /**
+         * Resource relationships
+         */
+        relationships: Data.Relationships;
+        type: 'payment';
     }
     namespace Data {
+        /**
+         * Resource attributes
+         */
         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
+         */
+        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;
+        }
+        namespace Relationships {
+            /**
+             * Payment request that produced this payment, when applicable.
+             */
+            interface PaymentRequest {
+                /**
+                 * Related resource identifier
+                 */
+                data: PaymentRequest.Data | null;
+            }
+            namespace PaymentRequest {
+                /**
+                 * Related resource identifier
+                 */
+                interface Data {
+                    id: string;
+                    /**
+                     * Resource type
+                     */
+                    type: 'paymentRequest';
+                }
+            }
+            /**
+             * Recipient party for this payment, when known.
+             */
+            interface Recipient {
+                /**
+                 * Related resource identifier
+                 */
+                data: Recipient.Data | null;
+            }
+            namespace Recipient {
+                /**
+                 * Related resource identifier
+                 */
+                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.
+             */
+            interface RecipientAgent {
+                /**
+                 * Related resource identifier
+                 */
+                data: RecipientAgent.Data | null;
+            }
+            namespace RecipientAgent {
+                /**
+                 * Related resource identifier
+                 */
+                interface Data {
+                    id: string;
+                    /**
+                     * Resource type
+                     */
+                    type: 'agent';
+                }
+            }
+            /**
+             * Party that initiated the payment
+             */
+            interface Sender {
+                /**
+                 * Related resource identifier
+                 */
+                data: Sender.Data;
+            }
+            namespace Sender {
+                /**
+                 * Related resource identifier
+                 */
+                interface Data {
+                    id: string;
+                    /**
+                     * Resource type
+                     */
+                    type: 'party';
+                }
+            }
+            /**
+             * Sender-side transaction row for this payment, when available.
+             */
+            interface Transaction {
+                /**
+                 * Related resource identifier
+                 */
+                data: Transaction.Data | null;
+            }
+            namespace Transaction {
+                /**
+                 * Related resource identifier
+                 */
+                interface Data {
+                    id: string;
+                    /**
+                     * Resource type
+                     */
+                    type: 'transaction';
+                }
+            }
         }
     }
 }
@@ -631,7 +865,7 @@ export declare namespace PaymentRequestGetResponse {
         /**
          * Resource type
          */
-        type: string;
+        type: 'paymentRequest';
     }
     namespace Data {
         /**
@@ -693,7 +927,7 @@ export declare 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
              * attempt yet
@@ -712,6 +946,10 @@ export declare namespace PaymentRequestGetResponse {
              * Resolved payer party, if the payer is known to Natural
              */
             payerParty: Relationships.PayerParty;
+            /**
+             * Payment submitted for this payment request, if one exists.
+             */
+            payment: Relationships.Payment;
             /**
              * Party requesting the payment
              */
@@ -740,7 +978,28 @@ export declare namespace PaymentRequestGetResponse {
                     /**
                      * Resource type
                      */
-                    type: string;
+                    type: 'party';
+                }
+            }
+            /**
+             * Payment submitted for this payment request, if one exists.
+             */
+            interface Payment {
+                /**
+                 * Related resource identifier
+                 */
+                data: Payment.Data | null;
+            }
+            namespace Payment {
+                /**
+                 * Related resource identifier
+                 */
+                interface Data {
+                    id: string;
+                    /**
+                     * Resource type
+                     */
+                    type: 'payment';
                 }
             }
             /**
@@ -761,7 +1020,7 @@ export declare namespace PaymentRequestGetResponse {
                     /**
                      * Resource type
                      */
-                    type: string;
+                    type: 'party';
                 }
             }
             /**
@@ -782,7 +1041,7 @@ export declare namespace PaymentRequestGetResponse {
                     /**
                      * Resource type
                      */
-                    type: string;
+                    type: 'wallet';
                 }
             }
         }
@@ -809,7 +1068,7 @@ export declare namespace PaymentRequestListIncomingResponse {
         /**
          * Resource type
          */
-        type: string;
+        type: 'paymentRequest';
     }
     namespace Data {
         /**
@@ -871,7 +1130,7 @@ export declare 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
              * attempt yet
@@ -890,6 +1149,10 @@ export declare namespace PaymentRequestListIncomingResponse {
              * Resolved payer party, if the payer is known to Natural
              */
             payerParty: Relationships.PayerParty;
+            /**
+             * Payment submitted for this payment request, if one exists.
+             */
+            payment: Relationships.Payment;
             /**
              * Party requesting the payment
              */
@@ -918,7 +1181,28 @@ export declare namespace PaymentRequestListIncomingResponse {
                     /**
                      * Resource type
                      */
-                    type: string;
+                    type: 'party';
+                }
+            }
+            /**
+             * Payment submitted for this payment request, if one exists.
+             */
+            interface Payment {
+                /**
+                 * Related resource identifier
+                 */
+                data: Payment.Data | null;
+            }
+            namespace Payment {
+                /**
+                 * Related resource identifier
+                 */
+                interface Data {
+                    id: string;
+                    /**
+                     * Resource type
+                     */
+                    type: 'payment';
                 }
             }
             /**
@@ -939,7 +1223,7 @@ export declare namespace PaymentRequestListIncomingResponse {
                     /**
                      * Resource type
                      */
-                    type: string;
+                    type: 'party';
                 }
             }
             /**
@@ -960,7 +1244,7 @@ export declare namespace PaymentRequestListIncomingResponse {
                     /**
                      * Resource type
                      */
-                    type: string;
+                    type: 'wallet';
                 }
             }
         }
@@ -984,12 +1268,20 @@ 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
      * same key was already processed, the original response is returned.
      */
     '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)
      */
@@ -1017,31 +1309,36 @@ 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 declare namespace PaymentRequestCreateParams {
     interface UnionMember0 {
-        type: string;
+        type: 'email';
         /**
          * Email address
          */
         value: string;
     }
     interface UnionMember1 {
-        type: string;
+        type: 'phone';
         /**
          * Phone number in E.164 format
          */
         value: string;
     }
+    interface UnionMember2 {
+        type: 'party_id';
+        /**
+         * Natural party ID (pty\_\*)
+         */
+        value: string;
+    }
+    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
@@ -1055,22 +1352,21 @@ export declare 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 {
     /**
@@ -1079,14 +1375,13 @@ 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 {
     /**
@@ -1099,54 +1394,51 @@ 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 declare namespace PaymentRequestFulfillParams {
     interface UnionMember0 {
-        type: string;
+        type: 'wallet';
         walletId: string;
     }
     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 {
     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, };