@naturalpay/sdk 0.3.0 → 0.4.0

package/resources/payment-requests.d.mts

@@ -12,7 +12,7 @@ export declare 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',
      * });
      * ```
@@ -27,6 +27,37 @@ export declare class PaymentRequests extends APIResource {
      * ```
      */
     list(params?: PaymentRequestListParams | null | undefined, options?: RequestOptions): APIPromise<PaymentRequestListResponse>;
+    /**
+     * 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>;
+    /**
+     * 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>;
     /**
      * Get a single payment request visible to the authenticated requester party.
      *
@@ -38,6 +69,16 @@ export declare class PaymentRequests extends APIResource {
      * ```
      */
     get(paymentRequestID: string, params?: PaymentRequestGetParams | null | undefined, options?: RequestOptions): APIPromise<PaymentRequestGetResponse>;
+    /**
+     * 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>;
 }
 export interface PaymentRequestCreateResponse {
     data: PaymentRequestCreateResponse.Data;
@@ -52,6 +93,10 @@ export declare namespace PaymentRequestCreateResponse {
          * Resource attributes
          */
         attributes: Data.Attributes;
+        /**
+         * Resource relationships
+         */
+        relationships: Data.Relationships;
         /**
          * Resource type
          */
@@ -75,7 +120,7 @@ export declare namespace PaymentRequestCreateResponse {
              */
             currency: string;
             /**
-             * Free-form description provided at creation
+             * Free-form description provided at creation. Maximum 500 characters.
              */
             description: string | null;
             /**
@@ -107,11 +152,11 @@ export declare 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;
             /**
@@ -128,6 +173,63 @@ export declare namespace PaymentRequestCreateResponse {
              */
             updatedAt: string;
         }
+        /**
+         * Resource relationships
+         */
+        interface Relationships {
+            /**
+             * Resolved payer party, if the payer is known to Natural
+             */
+            payerParty: Relationships.PayerParty;
+            /**
+             * Party requesting the payment
+             */
+            requesterParty: Relationships.RequesterParty;
+        }
+        namespace Relationships {
+            /**
+             * Resolved payer party, if the payer is known to Natural
+             */
+            interface PayerParty {
+                /**
+                 * Related resource identifier
+                 */
+                data: PayerParty.Data | null;
+            }
+            namespace PayerParty {
+                /**
+                 * Related resource identifier
+                 */
+                interface Data {
+                    id: string;
+                    /**
+                     * Resource type
+                     */
+                    type: string;
+                }
+            }
+            /**
+             * Party requesting the payment
+             */
+            interface RequesterParty {
+                /**
+                 * Related resource identifier
+                 */
+                data: RequesterParty.Data;
+            }
+            namespace RequesterParty {
+                /**
+                 * Related resource identifier
+                 */
+                interface Data {
+                    id: string;
+                    /**
+                     * Resource type
+                     */
+                    type: string;
+                }
+            }
+        }
     }
 }
 export interface PaymentRequestListResponse {
@@ -144,6 +246,10 @@ export declare namespace PaymentRequestListResponse {
          * Resource attributes
          */
         attributes: Data.Attributes;
+        /**
+         * Resource relationships
+         */
+        relationships: Data.Relationships;
         /**
          * Resource type
          */
@@ -167,7 +273,7 @@ export declare namespace PaymentRequestListResponse {
              */
             currency: string;
             /**
-             * Free-form description provided at creation
+             * Free-form description provided at creation. Maximum 500 characters.
              */
             description: string | null;
             /**
@@ -199,11 +305,11 @@ export declare 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;
             /**
@@ -220,6 +326,88 @@ export declare namespace PaymentRequestListResponse {
              */
             updatedAt: string;
         }
+        /**
+         * Resource relationships
+         */
+        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;
+        }
+        namespace Relationships {
+            /**
+             * Resolved payer party, if the payer is known to Natural
+             */
+            interface PayerParty {
+                /**
+                 * Related resource identifier
+                 */
+                data: PayerParty.Data | null;
+            }
+            namespace PayerParty {
+                /**
+                 * Related resource identifier
+                 */
+                interface Data {
+                    id: string;
+                    /**
+                     * Resource type
+                     */
+                    type: string;
+                }
+            }
+            /**
+             * Party requesting the payment
+             */
+            interface RequesterParty {
+                /**
+                 * Related resource identifier
+                 */
+                data: RequesterParty.Data;
+            }
+            namespace RequesterParty {
+                /**
+                 * Related resource identifier
+                 */
+                interface Data {
+                    id: string;
+                    /**
+                     * Resource type
+                     */
+                    type: string;
+                }
+            }
+            /**
+             * Wallet that receives the funds
+             */
+            interface Wallet {
+                /**
+                 * Related resource identifier
+                 */
+                data: Wallet.Data;
+            }
+            namespace Wallet {
+                /**
+                 * Related resource identifier
+                 */
+                interface Data {
+                    id: string;
+                    /**
+                     * Resource type
+                     */
+                    type: string;
+                }
+            }
+        }
     }
     interface Meta {
         pagination: Meta.Pagination;
@@ -231,6 +419,198 @@ export declare namespace PaymentRequestListResponse {
         }
     }
 }
+export interface PaymentRequestDeclineResponse {
+    data: PaymentRequestDeclineResponse.Data;
+}
+export declare namespace PaymentRequestDeclineResponse {
+    interface Data {
+        /**
+         * Resource ID (prq\_\*)
+         */
+        id: string;
+        /**
+         * Resource attributes
+         */
+        attributes: Data.Attributes;
+        /**
+         * Resource relationships
+         */
+        relationships: Data.Relationships;
+        /**
+         * Resource type
+         */
+        type: string;
+    }
+    namespace Data {
+        /**
+         * Resource attributes
+         */
+        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
+         */
+        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;
+        }
+        namespace Relationships {
+            /**
+             * Resolved payer party, if the payer is known to Natural
+             */
+            interface PayerParty {
+                /**
+                 * Related resource identifier
+                 */
+                data: PayerParty.Data | null;
+            }
+            namespace PayerParty {
+                /**
+                 * Related resource identifier
+                 */
+                interface Data {
+                    id: string;
+                    /**
+                     * Resource type
+                     */
+                    type: string;
+                }
+            }
+            /**
+             * Party requesting the payment
+             */
+            interface RequesterParty {
+                /**
+                 * Related resource identifier
+                 */
+                data: RequesterParty.Data;
+            }
+            namespace RequesterParty {
+                /**
+                 * Related resource identifier
+                 */
+                interface Data {
+                    id: string;
+                    /**
+                     * Resource type
+                     */
+                    type: string;
+                }
+            }
+            /**
+             * Wallet that receives the funds
+             */
+            interface Wallet {
+                /**
+                 * Related resource identifier
+                 */
+                data: Wallet.Data;
+            }
+            namespace Wallet {
+                /**
+                 * Related resource identifier
+                 */
+                interface Data {
+                    id: string;
+                    /**
+                     * Resource type
+                     */
+                    type: string;
+                }
+            }
+        }
+    }
+}
+export interface PaymentRequestFulfillResponse {
+    data: PaymentRequestFulfillResponse.Data;
+}
+export declare namespace PaymentRequestFulfillResponse {
+    interface Data {
+        id: string;
+        attributes: Data.Attributes;
+        type: string;
+    }
+    namespace Data {
+        interface Attributes {
+            outcome: 'processing' | 'failed' | 'completed' | 'in_review';
+        }
+    }
+}
 export interface PaymentRequestGetResponse {
     data: PaymentRequestGetResponse.Data;
 }
@@ -244,6 +624,10 @@ export declare namespace PaymentRequestGetResponse {
          * Resource attributes
          */
         attributes: Data.Attributes;
+        /**
+         * Resource relationships
+         */
+        relationships: Data.Relationships;
         /**
          * Resource type
          */
@@ -267,7 +651,7 @@ export declare namespace PaymentRequestGetResponse {
              */
             currency: string;
             /**
-             * Free-form description provided at creation
+             * Free-form description provided at creation. Maximum 500 characters.
              */
             description: string | null;
             /**
@@ -299,11 +683,11 @@ export declare 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;
             /**
@@ -320,17 +704,287 @@ export declare namespace PaymentRequestGetResponse {
              */
             updatedAt: string;
         }
+        /**
+         * Resource relationships
+         */
+        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;
+        }
+        namespace Relationships {
+            /**
+             * Resolved payer party, if the payer is known to Natural
+             */
+            interface PayerParty {
+                /**
+                 * Related resource identifier
+                 */
+                data: PayerParty.Data | null;
+            }
+            namespace PayerParty {
+                /**
+                 * Related resource identifier
+                 */
+                interface Data {
+                    id: string;
+                    /**
+                     * Resource type
+                     */
+                    type: string;
+                }
+            }
+            /**
+             * Party requesting the payment
+             */
+            interface RequesterParty {
+                /**
+                 * Related resource identifier
+                 */
+                data: RequesterParty.Data;
+            }
+            namespace RequesterParty {
+                /**
+                 * Related resource identifier
+                 */
+                interface Data {
+                    id: string;
+                    /**
+                     * Resource type
+                     */
+                    type: string;
+                }
+            }
+            /**
+             * Wallet that receives the funds
+             */
+            interface Wallet {
+                /**
+                 * Related resource identifier
+                 */
+                data: Wallet.Data;
+            }
+            namespace Wallet {
+                /**
+                 * Related resource identifier
+                 */
+                interface Data {
+                    id: string;
+                    /**
+                     * Resource type
+                     */
+                    type: string;
+                }
+            }
+        }
+    }
+}
+export interface PaymentRequestListIncomingResponse {
+    data: Array<PaymentRequestListIncomingResponse.Data>;
+    meta: PaymentRequestListIncomingResponse.Meta;
+}
+export declare namespace PaymentRequestListIncomingResponse {
+    interface Data {
+        /**
+         * Resource ID (prq\_\*)
+         */
+        id: string;
+        /**
+         * Resource attributes
+         */
+        attributes: Data.Attributes;
+        /**
+         * Resource relationships
+         */
+        relationships: Data.Relationships;
+        /**
+         * Resource type
+         */
+        type: string;
+    }
+    namespace Data {
+        /**
+         * Resource attributes
+         */
+        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
+         */
+        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;
+        }
+        namespace Relationships {
+            /**
+             * Resolved payer party, if the payer is known to Natural
+             */
+            interface PayerParty {
+                /**
+                 * Related resource identifier
+                 */
+                data: PayerParty.Data | null;
+            }
+            namespace PayerParty {
+                /**
+                 * Related resource identifier
+                 */
+                interface Data {
+                    id: string;
+                    /**
+                     * Resource type
+                     */
+                    type: string;
+                }
+            }
+            /**
+             * Party requesting the payment
+             */
+            interface RequesterParty {
+                /**
+                 * Related resource identifier
+                 */
+                data: RequesterParty.Data;
+            }
+            namespace RequesterParty {
+                /**
+                 * Related resource identifier
+                 */
+                interface Data {
+                    id: string;
+                    /**
+                     * Resource type
+                     */
+                    type: string;
+                }
+            }
+            /**
+             * Wallet that receives the funds
+             */
+            interface Wallet {
+                /**
+                 * Related resource identifier
+                 */
+                data: Wallet.Data;
+            }
+            namespace Wallet {
+                /**
+                 * Related resource identifier
+                 */
+                interface Data {
+                    id: string;
+                    /**
+                     * Resource type
+                     */
+                    type: string;
+                }
+            }
+        }
+    }
+    interface Meta {
+        pagination: Meta.Pagination;
+    }
+    namespace Meta {
+        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
      * same key was already processed, the original response is returned.
@@ -346,7 +1000,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;
     /**
@@ -375,30 +1029,16 @@ export interface PaymentRequestCreateParams {
 }
 export declare namespace PaymentRequestCreateParams {
     interface UnionMember0 {
-        kind: 'email';
+        type: string;
         /**
-         * Payer email address
+         * Email address
          */
         value: string;
     }
     interface UnionMember1 {
-        kind: 'phone';
-        /**
-         * Payer phone in E.164 format
-         */
-        value: string;
-    }
-    interface UnionMember2 {
-        kind: 'party_id';
-        /**
-         * Natural party ID (pty\_\*) of the payer
-         */
-        value: string;
-    }
-    interface UnionMember3 {
-        kind: 'agent_id';
+        type: string;
         /**
-         * Natural agent ID (agt\_\*) of the payer
+         * Phone number in E.164 format
          */
         value: string;
     }
@@ -432,6 +1072,52 @@ 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 declare namespace PaymentRequestFulfillParams {
+    interface UnionMember0 {
+        type: string;
+        walletId: string;
+    }
+    interface UnionMember1 {
+        externalAccountId: string;
+        type: string;
+    }
+}
 export interface PaymentRequestGetParams {
     /**
      * Agent ID (agt_xxx) identifying which agent is making the request.
@@ -443,7 +1129,26 @@ 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 PaymentRequestGetResponse as PaymentRequestGetResponse, type PaymentRequestCreateParams as PaymentRequestCreateParams, type PaymentRequestListParams as PaymentRequestListParams, type PaymentRequestGetParams as PaymentRequestGetParams, };
+    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, };
 }
 //# sourceMappingURL=payment-requests.d.mts.map