--- name: paytm-for-business-payment-failure-investigation description: Investigate one failed, pending or disputed Paytm payment the way an experienced payments support engineer does, starting from the order or transaction id, separating what the gateway recorded from what the customer experienced, checking refund and payment-link state, and ending in a stated cause with evidence. Use when the user asks why a payment failed, why a customer was charged but no order exists, why a payment is stuck pending, what happened to a specific order id or transaction id, or whether a failed payment was refunded. --- # Investigate a failed or disputed payment The goal is a **stated cause for one payment, with evidence**, not a guess from the status word. "FAILED" is a symptom. The cause is what the gateway recorded for this order or transaction, and whether the money actually moved. Work on one payment at a time. If the user has a period-level question (totals, missing settlements), hand that to the settlement reconciliation job instead. ## 1. Pin down the identifier and the merchant context Ask for the one identifier you have: an order id, a transaction id, or a payment link id. Do not start from a customer name or an amount, because those match many records. - Confirm which merchant account and environment (production or test) the user is looking at. Results from the wrong account look like missing data. - Note the amount, currency and the time the customer reports the problem. You will compare these against what the gateway returns. - If the identifier returns nothing, say so before changing the search. Check whether the id belongs to another account or environment, and only then consider that the record does not exist. ## 2. Read the order first, then the transaction behind it Use `fetch_order_status` for the order id. Record the order status, amount and the last update time. Then use `fetch_order_by_transaction_id` if the user has a transaction id instead, or to confirm which transaction the order points to. Read the two statuses separately: - **Order says failed, transaction says success:** the money may have been captured while the order was not completed. This is the most serious case. Treat it as a possible double-charge or unfulfilled order and move straight to the refund check. - **Order says pending, transaction says failed or absent:** the customer probably saw an error and retried. Check whether a later order or transaction carries the same amount and customer. - **Both say failed:** the payment did not move money. The customer's complaint is probably about a retry or a stale page, so check the payment options and card details for the cause. - **Multiple transactions on one order:** list each attempt in time order. The last successful one is the one that matters, and earlier failures usually explain the retries. ## 3. Check the payment method context Use `fetch_payment_options` to see which methods were offered for the merchant at that time, and `fetch_card_bin_details` if a card was used and the BIN is available from the record. Many failures come from the instrument, not the gateway: - **Card-type or issuer restriction:** the method was offered but this card's issuer or type is not supported for it. - **Method not enabled at the time:** the option list may have changed since the attempt. Say that you are reading the current list and may not match the list the customer saw. - **Card BIN from an unexpected country or issuer:** note it as context, and do not assume fraud from it alone. Only state a payment-method cause when the record supports it. If the BIN or option data is missing, say "payment method not determined". ## 4. Check the payment link, if one was used If the payment was made through a link, use `fetch_payment_links` to confirm the link is still active, has not expired and has not been used up, and `fetch_transactions_by_link_id` to see every attempt made through it. A link that is expired or inactive explains a customer who cannot pay, with no transaction at all. Several attempts on one link with the same failure point to a systematic cause, not a one-off. ## 5. Check refund state for any charged amount If money was captured but the order is not completed, or the customer reports a deduction on a failed order, check refunds: - `fetch_refund_status` for the refund id if one exists. - `fetch_refunds` to find refunds linked to the order or transaction when no refund id is known. Distinguish three states: no refund recorded, refund initiated but not complete, and refund completed. "Refund initiated" is not the same as "customer has the money". Tell the user this, and do not promise a timeframe that the record does not give. ## 6. Check subscriptions only when the payment is recurring If the failed payment belongs to a subscription, use `fetch_subscription_status`. A failed renewal can leave the subscription in a retry or paused state, and the next charge attempt matters more than the failed one. Do not check subscriptions for a one-off payment. ## 7. Form the cause, then test it against the record State the cause as "**the order failed because X, at step Y, at time Z**" and name the record that shows it. Then look for one fact that would disprove it: a successful transaction on the same order, a refund that contradicts the failure, or a payment method that was not offered. Confidence is high only when the status, the transaction attempt and the cause all agree in the records you read. ## Common patterns and traps - **Status word taken as the answer.** "FAILED" on the order can sit beside a captured transaction. Always read the transaction before concluding the customer was not charged. - **Retries mistaken for separate failures.** Several failed attempts followed by one success is one successful payment, not a failure. - **Wrong environment.** A test-mode id looked up in production returns nothing and looks like a missing order. Check the environment first. - **Refund initiated treated as refunded.** Report the actual state and what is still pending. - **Payment-method cause inferred without data.** If the BIN or option list is absent, leave the cause open rather than blaming the issuer. - **Customer's timeline not matched to the record.** A customer who saw a failure at 14:05 may have an attempt logged at a different time because of time zones. Check the record's time zone before comparing. - **Multiple orders with the same amount.** Match on the identifier, never on the amount alone. ## Output ``` Identifier: , merchant account , environment Order: , amount , last updated