@naturalpay/sdk 0.9.0 → 0.10.0

package/src/resources/payments.ts

@@ -18,7 +18,7 @@ export 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',
@@ -72,6 +72,40 @@ export class Payments extends APIResource {
     });
   }
 
+  /**
+   * 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' },
+   * );
+   * ```
+   */
+  cancel(
+    paymentID: string,
+    params: PaymentCancelParams,
+    options?: RequestOptions,
+  ): APIPromise<PaymentCancelResponse> {
+    const {
+      'Idempotency-Key': idempotencyKey,
+      'X-Agent-ID': xAgentID,
+      'X-Instance-ID': xInstanceID,
+    } = params;
+    return this._client.post(path`/payments/${paymentID}/cancel`, {
+      ...options,
+      headers: buildHeaders([
+        {
+          'Idempotency-Key': idempotencyKey,
+          ...(xAgentID != null ? { 'X-Agent-ID': xAgentID } : undefined),
+          ...(xInstanceID != null ? { 'X-Instance-ID': xInstanceID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
   /**
    * Get a payment initiated by the authenticated party.
    *
@@ -120,7 +154,7 @@ export namespace PaymentCreateResponse {
      */
     relationships: Data.Relationships;
 
-    type: string;
+    type: 'payment';
   }
 
   export namespace Data {
@@ -158,6 +192,7 @@ export namespace PaymentCreateResponse {
         | 'IN_REVIEW'
         | 'COMPLETED'
         | 'FAILED'
+        | 'RETURNED'
         | 'APPROVAL_DENIED'
         | 'CANCELLED';
 
@@ -171,11 +206,22 @@ export namespace PaymentCreateResponse {
      * Resource relationships
      */
     export interface Relationships {
+      /**
+       * Payment request that produced this payment, when applicable.
+       */
+      paymentRequest: Relationships.PaymentRequest;
+
       /**
        * Recipient party for this payment, when known.
        */
       recipient: Relationships.Recipient;
 
+      /**
+       * Recipient agent when the caller addressed an agent ID. Null otherwise, including
+       * when the recipient was addressed as an email, phone, or party ID.
+       */
+      recipientAgent: Relationships.RecipientAgent;
+
       /**
        * Party that initiated the payment
        */
@@ -188,6 +234,30 @@ export namespace PaymentCreateResponse {
     }
 
     export namespace Relationships {
+      /**
+       * Payment request that produced this payment, when applicable.
+       */
+      export interface PaymentRequest {
+        /**
+         * Related resource identifier
+         */
+        data: PaymentRequest.Data | null;
+      }
+
+      export namespace PaymentRequest {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: 'paymentRequest';
+        }
+      }
+
       /**
        * Recipient party for this payment, when known.
        */
@@ -208,7 +278,32 @@ export 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.
+       */
+      export interface RecipientAgent {
+        /**
+         * Related resource identifier
+         */
+        data: RecipientAgent.Data | null;
+      }
+
+      export namespace RecipientAgent {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: 'agent';
         }
       }
 
@@ -232,7 +327,7 @@ export namespace PaymentCreateResponse {
           /**
            * Resource type
            */
-          type: string;
+          type: 'party';
         }
       }
 
@@ -256,7 +351,7 @@ export namespace PaymentCreateResponse {
           /**
            * Resource type
            */
-          type: string;
+          type: 'transaction';
         }
       }
     }
@@ -283,7 +378,7 @@ export namespace PaymentListResponse {
      */
     relationships: Data.Relationships;
 
-    type: string;
+    type: 'payment';
   }
 
   export namespace Data {
@@ -321,6 +416,7 @@ export namespace PaymentListResponse {
         | 'IN_REVIEW'
         | 'COMPLETED'
         | 'FAILED'
+        | 'RETURNED'
         | 'APPROVAL_DENIED'
         | 'CANCELLED';
 
@@ -334,11 +430,22 @@ export namespace PaymentListResponse {
      * Resource relationships
      */
     export interface Relationships {
+      /**
+       * Payment request that produced this payment, when applicable.
+       */
+      paymentRequest: Relationships.PaymentRequest;
+
       /**
        * Recipient party for this payment, when known.
        */
       recipient: Relationships.Recipient;
 
+      /**
+       * Recipient agent when the caller addressed an agent ID. Null otherwise, including
+       * when the recipient was addressed as an email, phone, or party ID.
+       */
+      recipientAgent: Relationships.RecipientAgent;
+
       /**
        * Party that initiated the payment
        */
@@ -351,6 +458,30 @@ export namespace PaymentListResponse {
     }
 
     export namespace Relationships {
+      /**
+       * Payment request that produced this payment, when applicable.
+       */
+      export interface PaymentRequest {
+        /**
+         * Related resource identifier
+         */
+        data: PaymentRequest.Data | null;
+      }
+
+      export namespace PaymentRequest {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: 'paymentRequest';
+        }
+      }
+
       /**
        * Recipient party for this payment, when known.
        */
@@ -371,7 +502,32 @@ export 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.
+       */
+      export interface RecipientAgent {
+        /**
+         * Related resource identifier
+         */
+        data: RecipientAgent.Data | null;
+      }
+
+      export namespace RecipientAgent {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: 'agent';
         }
       }
 
@@ -395,7 +551,7 @@ export namespace PaymentListResponse {
           /**
            * Resource type
            */
-          type: string;
+          type: 'party';
         }
       }
 
@@ -419,7 +575,7 @@ export namespace PaymentListResponse {
           /**
            * Resource type
            */
-          type: string;
+          type: 'transaction';
         }
       }
     }
@@ -438,6 +594,228 @@ export namespace PaymentListResponse {
   }
 }
 
+export interface PaymentCancelResponse {
+  data: PaymentCancelResponse.Data;
+}
+
+export namespace PaymentCancelResponse {
+  export interface Data {
+    id: string;
+
+    /**
+     * Resource attributes
+     */
+    attributes: Data.Attributes;
+
+    /**
+     * Resource relationships
+     */
+    relationships: Data.Relationships;
+
+    type: 'payment';
+  }
+
+  export namespace Data {
+    /**
+     * Resource attributes
+     */
+    export 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
+     */
+    export interface Relationships {
+      /**
+       * Payment request that produced this payment, when applicable.
+       */
+      paymentRequest: Relationships.PaymentRequest;
+
+      /**
+       * Recipient party for this payment, when known.
+       */
+      recipient: Relationships.Recipient;
+
+      /**
+       * Recipient agent when the caller addressed an agent ID. Null otherwise, including
+       * when the recipient was addressed as an email, phone, or party ID.
+       */
+      recipientAgent: Relationships.RecipientAgent;
+
+      /**
+       * Party that initiated the payment
+       */
+      sender: Relationships.Sender;
+
+      /**
+       * Sender-side transaction row for this payment, when available.
+       */
+      transaction: Relationships.Transaction;
+    }
+
+    export namespace Relationships {
+      /**
+       * Payment request that produced this payment, when applicable.
+       */
+      export interface PaymentRequest {
+        /**
+         * Related resource identifier
+         */
+        data: PaymentRequest.Data | null;
+      }
+
+      export namespace PaymentRequest {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: 'paymentRequest';
+        }
+      }
+
+      /**
+       * Recipient party for this payment, when known.
+       */
+      export interface Recipient {
+        /**
+         * Related resource identifier
+         */
+        data: Recipient.Data | null;
+      }
+
+      export namespace Recipient {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: 'party';
+        }
+      }
+
+      /**
+       * Recipient agent when the caller addressed an agent ID. Null otherwise, including
+       * when the recipient was addressed as an email, phone, or party ID.
+       */
+      export interface RecipientAgent {
+        /**
+         * Related resource identifier
+         */
+        data: RecipientAgent.Data | null;
+      }
+
+      export namespace RecipientAgent {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: 'agent';
+        }
+      }
+
+      /**
+       * Party that initiated the payment
+       */
+      export interface Sender {
+        /**
+         * Related resource identifier
+         */
+        data: Sender.Data;
+      }
+
+      export namespace Sender {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: 'party';
+        }
+      }
+
+      /**
+       * Sender-side transaction row for this payment, when available.
+       */
+      export interface Transaction {
+        /**
+         * Related resource identifier
+         */
+        data: Transaction.Data | null;
+      }
+
+      export namespace Transaction {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: 'transaction';
+        }
+      }
+    }
+  }
+}
+
 export interface PaymentGetResponse {
   data: PaymentGetResponse.Data;
 }
@@ -456,7 +834,7 @@ export namespace PaymentGetResponse {
      */
     relationships: Data.Relationships;
 
-    type: string;
+    type: 'payment';
   }
 
   export namespace Data {
@@ -494,6 +872,7 @@ export namespace PaymentGetResponse {
         | 'IN_REVIEW'
         | 'COMPLETED'
         | 'FAILED'
+        | 'RETURNED'
         | 'APPROVAL_DENIED'
         | 'CANCELLED';
 
@@ -507,11 +886,22 @@ export namespace PaymentGetResponse {
      * Resource relationships
      */
     export interface Relationships {
+      /**
+       * Payment request that produced this payment, when applicable.
+       */
+      paymentRequest: Relationships.PaymentRequest;
+
       /**
        * Recipient party for this payment, when known.
        */
       recipient: Relationships.Recipient;
 
+      /**
+       * Recipient agent when the caller addressed an agent ID. Null otherwise, including
+       * when the recipient was addressed as an email, phone, or party ID.
+       */
+      recipientAgent: Relationships.RecipientAgent;
+
       /**
        * Party that initiated the payment
        */
@@ -524,6 +914,30 @@ export namespace PaymentGetResponse {
     }
 
     export namespace Relationships {
+      /**
+       * Payment request that produced this payment, when applicable.
+       */
+      export interface PaymentRequest {
+        /**
+         * Related resource identifier
+         */
+        data: PaymentRequest.Data | null;
+      }
+
+      export namespace PaymentRequest {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: 'paymentRequest';
+        }
+      }
+
       /**
        * Recipient party for this payment, when known.
        */
@@ -544,7 +958,32 @@ export 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.
+       */
+      export interface RecipientAgent {
+        /**
+         * Related resource identifier
+         */
+        data: RecipientAgent.Data | null;
+      }
+
+      export namespace RecipientAgent {
+        /**
+         * Related resource identifier
+         */
+        export interface Data {
+          id: string;
+
+          /**
+           * Resource type
+           */
+          type: 'agent';
         }
       }
 
@@ -568,7 +1007,7 @@ export namespace PaymentGetResponse {
           /**
            * Resource type
            */
-          type: string;
+          type: 'party';
         }
       }
 
@@ -592,7 +1031,7 @@ export namespace PaymentGetResponse {
           /**
            * Resource type
            */
-          type: string;
+          type: 'transaction';
         }
       }
     }
@@ -609,7 +1048,11 @@ 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
@@ -647,7 +1090,7 @@ export interface PaymentCreateParams {
 
 export namespace PaymentCreateParams {
   export interface UnionMember0 {
-    type: string;
+    type: 'email';
 
     /**
      * Email address
@@ -656,13 +1099,31 @@ export namespace PaymentCreateParams {
   }
 
   export interface UnionMember1 {
-    type: string;
+    type: 'phone';
 
     /**
      * Phone number in E.164 format
      */
     value: string;
   }
+
+  export interface UnionMember2 {
+    type: 'party_id';
+
+    /**
+     * Natural party ID (pty\_\*)
+     */
+    value: string;
+  }
+
+  export interface UnionMember3 {
+    type: 'agent_id';
+
+    /**
+     * Natural agent ID (agt\_\*)
+     */
+    value: string;
+  }
 }
 
 export interface PaymentListParams {
@@ -693,6 +1154,25 @@ export interface PaymentListParams {
   'X-Instance-ID'?: 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;
+
+  /**
+   * 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 PaymentGetParams {
   /**
    * Query param: Party ID for delegated payment lookup
@@ -715,9 +1195,11 @@ export declare namespace Payments {
   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,
   };
 }