@atumlabs/payment-gateway-client 2.1.0 → 2.2.0

package/dist/index.d.ts

@@ -445,10 +445,16 @@ type VerifiableCredential = {
     };
 };
 /**
- * Response from submitting a payment request. If processing completes within 30 seconds,
- * the response will include a fulfillment_confirmation with full settlement details.
- * Otherwise, you'll receive a payment_id that you can use to poll the
- * /v1/payments/{paymentId}/status endpoint for updates.
+ * Response from submitting a payment request. If settlement completes inside the
+ * gateway's synchronous window, the response includes a fulfillment_confirmation with
+ * full settlement details. Otherwise you receive a payment_id plus the payment's
+ * current `status`, and can poll /v1/payments/{paymentId}/status for updates.
+ *
+ * Read `status` before deciding what to do next: a `pending` payment is in flight and
+ * must NOT be re-submitted under a new request_id (that would be a second payment),
+ * whereas a `failed` or `cancelled` one is terminal — re-submitting it under the SAME
+ * request_id resolves to the same terminal payment, so a genuine re-attempt needs a
+ * new request_id.
  *
  */
 type PaymentResponse = {
@@ -456,9 +462,71 @@ type PaymentResponse = {
      * Unique ID for tracking this payment. Save this to check status later.
      *
      */
-    payment_id?: string;
+    payment_id: string;
+    /**
+     * Current status of the payment, with the same meaning as on
+     * /v1/payments/{paymentId}/status:
+     * - `pending`: accepted and being processed
+     * - `completed`: successfully delivered
+     * - `failed`: failed (funds returned if escrowed)
+     * - `cancelled`: cancelled before completion
+     *
+     * Present on every response. `completed` is always accompanied by
+     * fulfillment_confirmation; `failed` is accompanied by `error` where a reason has
+     * been recorded.
+     *
+     */
+    status: 'pending' | 'completed' | 'failed' | 'cancelled';
+    /**
+     * Whether this response describes a payment that already existed, rather than one
+     * created by this request. `true` means the request_id had been used before and you
+     * are being handed the ORIGINAL payment — no second payment was created and nothing
+     * additional was charged.
+     *
+     * **Re-attempting a payment.** Re-submit the same request and you get the same payment
+     * back. You may re-send the original bytes unchanged: the deadlines will have expired by
+     * then — `quote_deadline` bounds the auction and is short, while this endpoint may hold a
+     * submission for up to 30 seconds — and an expired deadline on a re-submission is not an
+     * error, because the request is resolved onto the payment that already exists rather than
+     * used to create one.
+     *
+     * Re-signing with fresh deadlines is equally fine and returns the same payment. What you
+     * must NOT change is the request_id, and what you must not change under it is the
+     * payment's economics — source, destination, fulfillment_amount, max_source_amount — which
+     * are rejected with 409 IDEMPOTENCY_TERMS_MISMATCH. Deadlines and the signature are
+     * exempt precisely so that a re-attempt is possible.
+     *
+     * A genuinely new payment needs a NEW request_id. In particular a `failed` payment is
+     * terminal: re-submitting its request_id keeps returning that dead payment, so recovering
+     * means starting a new one under a new key.
+     *
+     * Present on every response, `false` for a newly created payment. A response without
+     * the field is from a gateway predating it, not a newly created payment.
+     *
+     * This is the field to read when reconciling a suspected double charge: two
+     * submissions where the second reports `true` are one payment, whereas two both
+     * reporting `false` are two. It says nothing about how far the payment has got —
+     * read `status` for that.
+     *
+     */
+    idempotent_replay: boolean;
     fulfillment_confirmation?: FulfillmentConfirmation;
+    error?: PaymentError;
 };
+/**
+ * Current status of the payment, with the same meaning as on
+ * /v1/payments/{paymentId}/status:
+ * - `pending`: accepted and being processed
+ * - `completed`: successfully delivered
+ * - `failed`: failed (funds returned if escrowed)
+ * - `cancelled`: cancelled before completion
+ *
+ * Present on every response. `completed` is always accompanied by
+ * fulfillment_confirmation; `failed` is accompanied by `error` where a reason has
+ * been recorded.
+ *
+ */
+type status2 = 'pending' | 'completed' | 'failed' | 'cancelled';
 type GetPaymentStatusResponse = {
     /**
      * The payment ID you're checking status for.
@@ -481,15 +549,6 @@ type GetPaymentStatusResponse = {
     fulfillment_confirmation?: FulfillmentConfirmation;
     error?: PaymentError;
 };
-/**
- * Current status of your payment:
- * - `pending`: Payment is being processed
- * - `completed`: Payment successfully delivered
- * - `failed`: Payment failed (funds returned if escrowed)
- * - `cancelled`: Payment was cancelled before completion
- *
- */
-type status2 = 'pending' | 'completed' | 'failed' | 'cancelled';
 /**
  * Error details when payment status is "failed".
  * Only present when the payment has failed. Contains a machine-readable
@@ -1327,6 +1386,14 @@ type $OpenApiTs = {
                  * Payment declined during counterparty authorization
                  */
                 403: ErrorResponse;
+                /**
+                 * The `request_id` has already been used for a payment with different economics
+                 * (`IDEMPOTENCY_TERMS_MISMATCH`). Re-submitting one `request_id` is how a retry is
+                 * made safe, so it must identify one payment; use a distinct `request_id` per
+                 * payment.
+                 *
+                 */
+                409: ErrorResponse;
                 /**
                  * Payment request too large to process
                  */
@@ -1555,8 +1622,26 @@ declare class PaymentsService {
      * 2. Find optimal settlement routes across chains/assets
      * 3. Secure funds in escrow
      * 4. Coordinate with settlement agents for execution
-     * 5. Return a real-time result if processing completes within 30 seconds,
-     * otherwise return a payment ID for status polling
+     * 5. Return a real-time result if settlement completes inside the synchronous window,
+     * otherwise return a payment ID and status for polling
+     *
+     * **Idempotency.** `request_id` is the idempotency key, scoped to the source account
+     * and originator. Submitting the same `request_id` again returns the ORIGINAL payment
+     * instead of charging a second time, so a client whose request timed out or failed
+     * in transit can safely re-submit.
+     *
+     * Because a re-submission must be admissible on its own, some fields legitimately
+     * differ between attempts and are excluded from the comparison: `quote_deadline` and
+     * `fulfillment_deadline` (both must be in the future, so a later attempt has to move
+     * them), and the `sender_auth` signature they are signed into.
+     *
+     * What must NOT differ is the payment's economics — source account and asset,
+     * destination accounts and assets, `fulfillment_amount`, and `max_source_amount` (the
+     * payer's own risk cap; lowering it on a retry describes a different payment, not the
+     * same one with less headroom). Re-using one `request_id` for a genuinely different
+     * payment is a client bug that would otherwise be silently collapsed onto the first
+     * payment, so it is rejected with `409` and `IDEMPOTENCY_TERMS_MISMATCH`. Use a
+     * distinct `request_id` per payment.
      *
      * @param data The data for the request.
      * @param data.requestBody
@@ -2251,16 +2336,30 @@ declare const $VerifiableCredential: {
 };
 declare const $PaymentResponse: {
     readonly type: "object";
-    readonly description: "Response from submitting a payment request. If processing completes within 30 seconds,\nthe response will include a fulfillment_confirmation with full settlement details.\nOtherwise, you'll receive a payment_id that you can use to poll the\n/v1/payments/{paymentId}/status endpoint for updates.\n";
+    readonly description: "Response from submitting a payment request. If settlement completes inside the\ngateway's synchronous window, the response includes a fulfillment_confirmation with\nfull settlement details. Otherwise you receive a payment_id plus the payment's\ncurrent `status`, and can poll /v1/payments/{paymentId}/status for updates.\n\nRead `status` before deciding what to do next: a `pending` payment is in flight and\nmust NOT be re-submitted under a new request_id (that would be a second payment),\nwhereas a `failed` or `cancelled` one is terminal — re-submitting it under the SAME\nrequest_id resolves to the same terminal payment, so a genuine re-attempt needs a\nnew request_id.\n";
+    readonly required: readonly ["payment_id", "status", "idempotent_replay"];
     readonly properties: {
         readonly payment_id: {
             readonly type: "string";
             readonly description: "Unique ID for tracking this payment. Save this to check status later.\n";
             readonly example: "550e8400-e29b-41d4-a716-446655440000";
         };
+        readonly status: {
+            readonly type: "string";
+            readonly enum: readonly ["pending", "completed", "failed", "cancelled"];
+            readonly description: "Current status of the payment, with the same meaning as on\n/v1/payments/{paymentId}/status:\n- `pending`: accepted and being processed\n- `completed`: successfully delivered\n- `failed`: failed (funds returned if escrowed)\n- `cancelled`: cancelled before completion\n\nPresent on every response. `completed` is always accompanied by\nfulfillment_confirmation; `failed` is accompanied by `error` where a reason has\nbeen recorded.\n";
+        };
+        readonly idempotent_replay: {
+            readonly type: "boolean";
+            readonly description: "Whether this response describes a payment that already existed, rather than one\ncreated by this request. `true` means the request_id had been used before and you\nare being handed the ORIGINAL payment — no second payment was created and nothing\nadditional was charged.\n\n**Re-attempting a payment.** Re-submit the same request and you get the same payment\nback. You may re-send the original bytes unchanged: the deadlines will have expired by\nthen — `quote_deadline` bounds the auction and is short, while this endpoint may hold a\nsubmission for up to 30 seconds — and an expired deadline on a re-submission is not an\nerror, because the request is resolved onto the payment that already exists rather than\nused to create one.\n\nRe-signing with fresh deadlines is equally fine and returns the same payment. What you\nmust NOT change is the request_id, and what you must not change under it is the\npayment's economics — source, destination, fulfillment_amount, max_source_amount — which\nare rejected with 409 IDEMPOTENCY_TERMS_MISMATCH. Deadlines and the signature are\nexempt precisely so that a re-attempt is possible.\n\nA genuinely new payment needs a NEW request_id. In particular a `failed` payment is\nterminal: re-submitting its request_id keeps returning that dead payment, so recovering\nmeans starting a new one under a new key.\n\nPresent on every response, `false` for a newly created payment. A response without\nthe field is from a gateway predating it, not a newly created payment.\n\nThis is the field to read when reconciling a suspected double charge: two\nsubmissions where the second reports `true` are one payment, whereas two both\nreporting `false` are two. It says nothing about how far the payment has got —\nread `status` for that.\n";
+            readonly example: false;
+        };
         readonly fulfillment_confirmation: {
             readonly $ref: "#/components/schemas/FulfillmentConfirmation";
         };
+        readonly error: {
+            readonly $ref: "#/components/schemas/PaymentError";
+        };
     };
 };
 declare const $GetPaymentStatusResponse: {