@naturalpay/sdk 0.9.0 → 0.11.0

package/resources/payments.d.ts

@@ -13,10 +13,12 @@ export declare class Payments extends APIResource {
      * const payment = await client.payments.create({
      *   amount: 1,
      *   counterparty: {
-     *     type: 'type',
+     *     type: 'email',
      *     value: 'dev@stainless.com',
      *   },
      *   'Idempotency-Key': 'Idempotency-Key',
+     *   'X-Agent-ID': 'X-Agent-ID',
+     *   'X-Instance-ID': 'X-Instance-ID',
      * });
      * ```
      */
@@ -26,10 +28,29 @@ export declare class Payments extends APIResource {
      *
      * @example
      * ```ts
-     * const payments = await client.payments.list();
+     * const payments = await client.payments.list({
+     *   'X-Agent-ID': 'X-Agent-ID',
+     *   'X-Instance-ID': 'X-Instance-ID',
+     * });
+     * ```
+     */
+    list(params: PaymentListParams, options?: RequestOptions): APIPromise<PaymentListResponse>;
+    /**
+     * Cancel a pending-claim payment before the recipient starts claiming it.
+     *
+     * @example
+     * ```ts
+     * const response = await client.payments.cancel(
+     *   'pay_ecc2efdd09bd231a9ad9bd2aada37aa7',
+     *   {
+     *     'Idempotency-Key': 'Idempotency-Key',
+     *     'X-Agent-ID': 'X-Agent-ID',
+     *     'X-Instance-ID': 'X-Instance-ID',
+     *   },
+     * );
      * ```
      */
-    list(params?: PaymentListParams | null | undefined, options?: RequestOptions): APIPromise<PaymentListResponse>;
+    cancel(paymentID: string, params: PaymentCancelParams, options?: RequestOptions): APIPromise<PaymentCancelResponse>;
     /**
      * Get a payment initiated by the authenticated party.
      *
@@ -37,10 +58,14 @@ export declare class Payments extends APIResource {
      * ```ts
      * const payment = await client.payments.get(
      *   'pay_ecc2efdd09bd231a9ad9bd2aada37aa7',
+     *   {
+     *     'X-Agent-ID': 'X-Agent-ID',
+     *     'X-Instance-ID': 'X-Instance-ID',
+     *   },
      * );
      * ```
      */
-    get(paymentID: string, params?: PaymentGetParams | null | undefined, options?: RequestOptions): APIPromise<PaymentGetResponse>;
+    get(paymentID: string, params: PaymentGetParams, options?: RequestOptions): APIPromise<PaymentGetResponse>;
 }
 export interface PaymentCreateResponse {
     data: PaymentCreateResponse.Data;
@@ -56,7 +81,7 @@ export declare namespace PaymentCreateResponse {
          * Resource relationships
          */
         relationships: Data.Relationships;
-        type: string;
+        type: 'payment';
     }
     namespace Data {
         /**
@@ -82,7 +107,7 @@ export declare namespace PaymentCreateResponse {
             /**
              * Payment status
              */
-            status: 'CREATED' | 'PROCESSING' | 'PENDING_CLAIM' | 'IN_REVIEW' | 'COMPLETED' | 'FAILED' | 'APPROVAL_DENIED' | 'CANCELLED';
+            status: 'CREATED' | 'PROCESSING' | 'PENDING_CLAIM' | 'IN_REVIEW' | 'COMPLETED' | 'FAILED' | 'RETURNED' | 'APPROVAL_DENIED' | 'CANCELLED';
             /**
              * When this payment was last updated
              */
@@ -92,10 +117,19 @@ export declare namespace PaymentCreateResponse {
          * 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
              */
@@ -106,6 +140,27 @@ export declare namespace PaymentCreateResponse {
             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.
              */
@@ -124,7 +179,29 @@ export declare namespace PaymentCreateResponse {
                     /**
                      * Resource type
                      */
-                    type: string;
+                    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';
                 }
             }
             /**
@@ -145,7 +222,7 @@ export declare namespace PaymentCreateResponse {
                     /**
                      * Resource type
                      */
-                    type: string;
+                    type: 'party';
                 }
             }
             /**
@@ -166,7 +243,7 @@ export declare namespace PaymentCreateResponse {
                     /**
                      * Resource type
                      */
-                    type: string;
+                    type: 'transaction';
                 }
             }
         }
@@ -187,7 +264,7 @@ export declare namespace PaymentListResponse {
          * Resource relationships
          */
         relationships: Data.Relationships;
-        type: string;
+        type: 'payment';
     }
     namespace Data {
         /**
@@ -213,7 +290,7 @@ export declare namespace PaymentListResponse {
             /**
              * Payment status
              */
-            status: 'CREATED' | 'PROCESSING' | 'PENDING_CLAIM' | 'IN_REVIEW' | 'COMPLETED' | 'FAILED' | 'APPROVAL_DENIED' | 'CANCELLED';
+            status: 'CREATED' | 'PROCESSING' | 'PENDING_CLAIM' | 'IN_REVIEW' | 'COMPLETED' | 'FAILED' | 'RETURNED' | 'APPROVAL_DENIED' | 'CANCELLED';
             /**
              * When this payment was last updated
              */
@@ -223,10 +300,19 @@ export declare namespace PaymentListResponse {
          * 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
              */
@@ -237,6 +323,27 @@ export declare namespace PaymentListResponse {
             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.
              */
@@ -255,7 +362,29 @@ export declare namespace PaymentListResponse {
                     /**
                      * Resource type
                      */
-                    type: string;
+                    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';
                 }
             }
             /**
@@ -276,7 +405,7 @@ export declare namespace PaymentListResponse {
                     /**
                      * Resource type
                      */
-                    type: string;
+                    type: 'party';
                 }
             }
             /**
@@ -297,7 +426,7 @@ export declare namespace PaymentListResponse {
                     /**
                      * Resource type
                      */
-                    type: string;
+                    type: 'transaction';
                 }
             }
         }
@@ -312,6 +441,188 @@ export declare namespace PaymentListResponse {
         }
     }
 }
+export interface PaymentCancelResponse {
+    data: PaymentCancelResponse.Data;
+}
+export declare namespace PaymentCancelResponse {
+    interface Data {
+        id: string;
+        /**
+         * Resource attributes
+         */
+        attributes: Data.Attributes;
+        /**
+         * Resource relationships
+         */
+        relationships: Data.Relationships;
+        type: 'payment';
+    }
+    namespace Data {
+        /**
+         * Resource attributes
+         */
+        interface Attributes {
+            /**
+             * 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';
+                }
+            }
+        }
+    }
+}
 export interface PaymentGetResponse {
     data: PaymentGetResponse.Data;
 }
@@ -326,7 +637,7 @@ export declare namespace PaymentGetResponse {
          * Resource relationships
          */
         relationships: Data.Relationships;
-        type: string;
+        type: 'payment';
     }
     namespace Data {
         /**
@@ -352,7 +663,7 @@ export declare namespace PaymentGetResponse {
             /**
              * Payment status
              */
-            status: 'CREATED' | 'PROCESSING' | 'PENDING_CLAIM' | 'IN_REVIEW' | 'COMPLETED' | 'FAILED' | 'APPROVAL_DENIED' | 'CANCELLED';
+            status: 'CREATED' | 'PROCESSING' | 'PENDING_CLAIM' | 'IN_REVIEW' | 'COMPLETED' | 'FAILED' | 'RETURNED' | 'APPROVAL_DENIED' | 'CANCELLED';
             /**
              * When this payment was last updated
              */
@@ -362,10 +673,19 @@ export declare namespace PaymentGetResponse {
          * 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
              */
@@ -376,6 +696,27 @@ export declare namespace PaymentGetResponse {
             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.
              */
@@ -394,7 +735,29 @@ export declare namespace PaymentGetResponse {
                     /**
                      * Resource type
                      */
-                    type: string;
+                    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';
                 }
             }
             /**
@@ -415,7 +778,7 @@ export declare namespace PaymentGetResponse {
                     /**
                      * Resource type
                      */
-                    type: string;
+                    type: 'party';
                 }
             }
             /**
@@ -436,7 +799,7 @@ export declare namespace PaymentGetResponse {
                     /**
                      * Resource type
                      */
-                    type: string;
+                    type: 'transaction';
                 }
             }
         }
@@ -451,12 +814,20 @@ export interface PaymentCreateParams {
      * Body param: Recipient identifier. Provide exactly one typed email, phone, party
      * ID, or agent ID value.
      */
-    counterparty: PaymentCreateParams.UnionMember0 | PaymentCreateParams.UnionMember1;
+    counterparty: PaymentCreateParams.UnionMember0 | PaymentCreateParams.UnionMember1 | PaymentCreateParams.UnionMember2 | PaymentCreateParams.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
      */
@@ -470,33 +841,46 @@ export interface PaymentCreateParams {
      * Body param: Payment description. Maximum 500 characters.
      */
     description?: 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 PaymentCreateParams {
     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;
+    }
 }
 export interface PaymentListParams {
+    /**
+     * 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;
     /**
      * Query param: Pagination cursor from previous response
      */
@@ -509,32 +893,37 @@ export interface PaymentListParams {
      * Query param: Party ID for delegated payment lookup
      */
     partyId?: string;
+}
+export interface PaymentCancelParams {
+    /**
+     * 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.
+     * 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.
+     * Stable run, session, or conversation ID for agent observability.
      */
-    'X-Instance-ID'?: string;
+    'X-Instance-ID': string;
 }
 export interface PaymentGetParams {
     /**
-     * Query param: Party ID for delegated payment lookup
+     * Header param: Agent ID (agt_xxx) used for attribution and audit.
      */
-    partyId?: string;
+    'X-Agent-ID': string;
     /**
-     * Header param: Agent ID (agt_xxx) identifying which agent is making the request.
+     * Header param: Stable run, session, or conversation ID for agent observability.
      */
-    'X-Agent-ID'?: string;
+    'X-Instance-ID': string;
     /**
-     * Header param: Required when X-Agent-ID is present. Session or conversation ID
-     * for agent observability.
+     * Query param: Party ID for delegated payment lookup
      */
-    'X-Instance-ID'?: string;
+    partyId?: string;
 }
 export declare namespace Payments {
-    export { type PaymentCreateResponse as PaymentCreateResponse, type PaymentListResponse as PaymentListResponse, type PaymentGetResponse as PaymentGetResponse, type PaymentCreateParams as PaymentCreateParams, type PaymentListParams as PaymentListParams, type PaymentGetParams as PaymentGetParams, };
+    export { type PaymentCreateResponse as PaymentCreateResponse, type PaymentListResponse as PaymentListResponse, type PaymentCancelResponse as PaymentCancelResponse, type PaymentGetResponse as PaymentGetResponse, type PaymentCreateParams as PaymentCreateParams, type PaymentListParams as PaymentListParams, type PaymentCancelParams as PaymentCancelParams, type PaymentGetParams as PaymentGetParams, };
 }
 //# sourceMappingURL=payments.d.ts.map