@naturalpay/sdk 0.2.0 → 0.3.0

package/src/resources/payment-requests.ts

@@ -0,0 +1,611 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import { APIPromise } from '../core/api-promise';
+import { buildHeaders } from '../internal/headers';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+/**
+ * Payment-request management
+ */
+export class PaymentRequests extends APIResource {
+  /**
+   * Create a payment request and optionally send the link immediately.
+   *
+   * @example
+   * ```ts
+   * const paymentRequest = await client.paymentRequests.create({
+   *   amount: 1,
+   *   payer: { kind: 'email', value: 'dev@stainless.com' },
+   *   'Idempotency-Key': 'Idempotency-Key',
+   * });
+   * ```
+   */
+  create(
+    params: PaymentRequestCreateParams,
+    options?: RequestOptions,
+  ): APIPromise<PaymentRequestCreateResponse> {
+    const {
+      'Idempotency-Key': idempotencyKey,
+      'X-Agent-ID': xAgentID,
+      'X-Instance-ID': xInstanceID,
+      ...body
+    } = params;
+    return this._client.post('/payment-requests', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          'Idempotency-Key': idempotencyKey,
+          ...(xAgentID != null ? { 'X-Agent-ID': xAgentID } : undefined),
+          ...(xInstanceID != null ? { 'X-Instance-ID': xInstanceID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * List payment requests visible to the authenticated requester party.
+   *
+   * @example
+   * ```ts
+   * const paymentRequests = await client.paymentRequests.list();
+   * ```
+   */
+  list(
+    params: PaymentRequestListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<PaymentRequestListResponse> {
+    const { 'X-Agent-ID': xAgentID, 'X-Instance-ID': xInstanceID, ...query } = params ?? {};
+    return this._client.get('/payment-requests', {
+      query,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xAgentID != null ? { 'X-Agent-ID': xAgentID } : undefined),
+          ...(xInstanceID != null ? { 'X-Instance-ID': xInstanceID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Get a single payment request visible to the authenticated requester party.
+   *
+   * @example
+   * ```ts
+   * const paymentRequest = await client.paymentRequests.get(
+   *   'prq_ecc2efdd09bd231a9ad9bd2aada37aa7',
+   * );
+   * ```
+   */
+  get(
+    paymentRequestID: string,
+    params: PaymentRequestGetParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<PaymentRequestGetResponse> {
+    const { 'X-Agent-ID': xAgentID, 'X-Instance-ID': xInstanceID } = params ?? {};
+    return this._client.get(path`/payment-requests/${paymentRequestID}`, {
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xAgentID != null ? { 'X-Agent-ID': xAgentID } : undefined),
+          ...(xInstanceID != null ? { 'X-Instance-ID': xInstanceID } : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+}
+
+export interface PaymentRequestCreateResponse {
+  data: PaymentRequestCreateResponse.Data;
+}
+
+export namespace PaymentRequestCreateResponse {
+  export interface Data {
+    /**
+     * Resource ID (prq\_\*)
+     */
+    id: string;
+
+    /**
+     * Resource attributes
+     */
+    attributes: Data.Attributes;
+
+    /**
+     * Resource type
+     */
+    type: string;
+  }
+
+  export namespace Data {
+    /**
+     * Resource attributes
+     */
+    export interface Attributes {
+      /**
+       * Amount in cents
+       */
+      amount: number;
+
+      /**
+       * ISO 8601 timestamp when the payment request was created
+       */
+      createdAt: string;
+
+      /**
+       * Currency code
+       */
+      currency: string;
+
+      /**
+       * Free-form description provided at creation
+       */
+      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 requester party
+       */
+      requesterEmail: string | null;
+
+      /**
+       * Display name of the requester party
+       */
+      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;
+    }
+  }
+}
+
+export interface PaymentRequestListResponse {
+  data: Array<PaymentRequestListResponse.Data>;
+
+  meta: PaymentRequestListResponse.Meta;
+}
+
+export namespace PaymentRequestListResponse {
+  export interface Data {
+    /**
+     * Resource ID (prq\_\*)
+     */
+    id: string;
+
+    /**
+     * Resource attributes
+     */
+    attributes: Data.Attributes;
+
+    /**
+     * Resource type
+     */
+    type: string;
+  }
+
+  export namespace Data {
+    /**
+     * Resource attributes
+     */
+    export interface Attributes {
+      /**
+       * Amount in cents
+       */
+      amount: number;
+
+      /**
+       * ISO 8601 timestamp when the payment request was created
+       */
+      createdAt: string;
+
+      /**
+       * Currency code
+       */
+      currency: string;
+
+      /**
+       * Free-form description provided at creation
+       */
+      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 requester party
+       */
+      requesterEmail: string | null;
+
+      /**
+       * Display name of the requester party
+       */
+      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;
+    }
+  }
+
+  export interface Meta {
+    pagination: Meta.Pagination;
+  }
+
+  export namespace Meta {
+    export interface Pagination {
+      hasMore: boolean;
+
+      nextCursor: string | null;
+    }
+  }
+}
+
+export interface PaymentRequestGetResponse {
+  data: PaymentRequestGetResponse.Data;
+}
+
+export namespace PaymentRequestGetResponse {
+  export interface Data {
+    /**
+     * Resource ID (prq\_\*)
+     */
+    id: string;
+
+    /**
+     * Resource attributes
+     */
+    attributes: Data.Attributes;
+
+    /**
+     * Resource type
+     */
+    type: string;
+  }
+
+  export namespace Data {
+    /**
+     * Resource attributes
+     */
+    export interface Attributes {
+      /**
+       * Amount in cents
+       */
+      amount: number;
+
+      /**
+       * ISO 8601 timestamp when the payment request was created
+       */
+      createdAt: string;
+
+      /**
+       * Currency code
+       */
+      currency: string;
+
+      /**
+       * Free-form description provided at creation
+       */
+      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 requester party
+       */
+      requesterEmail: string | null;
+
+      /**
+       * Display name of the requester party
+       */
+      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;
+    }
+  }
+}
+
+export interface PaymentRequestCreateParams {
+  /**
+   * Body param: Amount in cents
+   */
+  amount: number;
+
+  /**
+   * Body param: Who pays — exactly one of email, phone, party, or agent.
+   */
+  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;
+
+  /**
+   * Body param: Currency code (currently only USD)
+   */
+  currency?: 'USD';
+
+  /**
+   * Body param: Requester party ID (pty\_\*). Omit to request into your own wallet;
+   * provide for delegated payment requests on behalf of a customer.
+   */
+  customerPartyId?: string;
+
+  /**
+   * Body param: Free-form description shown to the payer
+   */
+  description?: string;
+
+  /**
+   * Body param: Display name of the payer
+   */
+  payerName?: string;
+
+  /**
+   * Body param: If provided, immediately deliver the payment link to the payer via
+   * the named channel
+   */
+  sendLink?: PaymentRequestCreateParams.SendLink;
+
+  /**
+   * Body param: Wallet that should receive the funds. Omit to use the requester
+   * 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 namespace PaymentRequestCreateParams {
+  export interface UnionMember0 {
+    kind: 'email';
+
+    /**
+     * Payer email address
+     */
+    value: string;
+  }
+
+  export interface UnionMember1 {
+    kind: 'phone';
+
+    /**
+     * Payer phone in E.164 format
+     */
+    value: string;
+  }
+
+  export interface UnionMember2 {
+    kind: 'party_id';
+
+    /**
+     * Natural party ID (pty\_\*) of the payer
+     */
+    value: string;
+  }
+
+  export interface UnionMember3 {
+    kind: 'agent_id';
+
+    /**
+     * Natural agent ID (agt\_\*) of the payer
+     */
+    value: string;
+  }
+
+  /**
+   * If provided, immediately deliver the payment link to the payer via the named
+   * channel
+   */
+  export interface SendLink {
+    /**
+     * Channel to deliver the payment link
+     */
+    channel: 'EMAIL' | 'SMS';
+  }
+}
+
+export interface PaymentRequestListParams {
+  /**
+   * 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 interface PaymentRequestGetParams {
+  /**
+   * 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 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,
+  };
+}