--- name: checkout-com-payment-status-investigation description: Trace the state of one Checkout.com payment, or a small set of payments, using the payment-actions tools to read its details, its actions and its processing channel, then explain why it is in its current state and say what is verified and what is not. Read-only and separate from building an integration. Use when the user asks why a payment failed, is pending, was declined, was captured or refunded unexpectedly, or wants the status of a payment id. --- # Investigate a payment's status The job is to explain **what state a payment is in, and why**, from live data. It is not to guess from the payment method or to design code. A correct answer names the payment id, its current status, the actions that have happened to it, and the processing channel it went through, each backed by a value the tools returned. ## 1. Confirm the environment and entity before reading anything Payments exist only in one environment and under one entity. Look at the wrong one and you will explain a payment that does not exist, or the wrong one. - Ask which environment the user is in (sandbox or production) if it is not already clear from the connection they use. Sandbox and production payments do not mix. - Call `payment-actions___list_entities` to see which entities the account can see and which one is active. If the payment id is not found, the first suspect is the entity, not the payment. - If the active entity is not the one the payment belongs to, stop and ask the user. Switching the active entity changes the context of every later call, so wait for the user's explicit yes before switching it. Do not switch it silently to make a lookup work. ## 2. Get the payment's current state Call `payment-actions___get_payment_details` with the payment id. Record the status and the amounts exactly as returned: authorised, captured, refunded, voided, declined, pending, and so on. Note the currency, the requested amount, the captured or refunded amount, and the timestamps. A payment whose captured amount is less than its authorised amount is a partial capture, not an error, and the reason often sits in the actions. If the lookup fails with a not-found error, check step 1 before you conclude anything. If it fails with a permission error, report that you were blocked and stop; do not work around it. ## 3. Reconstruct what happened, in order Call `payment-actions___get_payment_actions` for the same payment. Actions are the history: authorisations, captures, refunds, voids, and the attempts that led to them. Read them **oldest first**. The current status is the result of the sequence, and a single action rarely explains it alone. For each action, note its type, its result and its time. Then ask: - Was there more than one authorisation attempt? If so, the first attempt's result is usually the one that explains a later decline or retry. - Was a capture sent before the authorisation completed, or after a void? Ordering explains many "impossible" states. - Is there a refund or void that reversed a capture? The net amount is the captured amount minus the refunded amount, and that is the figure to report. ## 4. Check the processing channel Call `payment-actions___list_processing_channels` to see the channels available, then use the channel identified on the payment to explain routing. A decline that looks like a card problem is often a channel or configuration problem; a payment routed to a channel the user did not expect is a finding in its own right. Report the channel's name as returned. Do not describe how a channel works internally unless the docs confirm it. ## 5. Use the documentation only to interpret codes When an action or status carries a code or reason you cannot interpret, use `developer-documentation___docs_search`, `developer-documentation___api_search` or `developer-documentation___support_search` to find what it means, and cite where you found it. Use `developer-documentation___docs_fetch` to read a full page once you have its address. Do not explain a response code from memory. If the docs do not define it, say so and report the raw value. ## 6. Form a finding and test it State the finding as: "Payment **P** is **status S** because **action A** (at time T, result R) followed by **action B**, routed through channel C." Then look for one fact that would contradict it, such as another payment with the same reference that succeeded, or an action missing from the history. If the contradiction cannot be ruled out, lower your confidence and say which fact would settle it. Use the `payment-actions` tools for the live facts and the `developer-documentation` tools only for meaning. Never present a documentation search as evidence about this specific payment. ## Common patterns and traps - **Not found, but the payment exists:** wrong environment or wrong entity. Check step 1 before anything else. - **Captured less than authorised:** a partial capture, which is normal. Check whether a later action released or reduced the rest before calling it a fault. - **Status says declined, but there is a later successful authorisation:** the decline was an earlier attempt. Report the latest successful state and show the attempt history. - **Refund shown but the customer was not refunded:** a refund action is a request. Report what the action says and do not promise the money has arrived. - **Pending for a long time:** check the actions for an authorisation or capture with no final result before concluding it is stuck. A missing result is itself the finding. - **Two payments that look the same:** compare ids and entity before comparing states. Duplicate-looking payments are often separate attempts. - **Blaming the card or issuer:** only say this if an action or code states it. Otherwise report the channel and the result as recorded. - **Treating a docs example as this payment's data:** examples in documentation are illustrative. Only the values from `payment-actions___get_payment_details` and `payment-actions___get_payment_actions` describe the payment. ## Output ``` Payment: Environment: Entity: Status: Requested: Captured: Refunded: Processing channel: History (oldest first): 1.