> ## Documentation Index
> Fetch the complete documentation index at: https://docs.natural.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> When building application code, use `@naturalpay/sdk` for TypeScript or `naturalpay` for Python.
> When operating Natural directly for a user, use the payments MCP at `https://mcp.natural.com`.
> When searching Natural documentation, use the docs MCP at `https://docs.natural.com/mcp`.
> Use the Natural CLI for terminal and CI automation.
> Use REST only for unsupported languages or when the user explicitly requests raw HTTP.
> Start integration development and testing in the sandbox. Do not use production unless the user explicitly requests it.
> For sandbox requests that require `customerPartyId`, list customers first. Reuse only the intended fixture; otherwise create a customer.
> REST and SDK amounts use integer minor units. Payments MCP amounts use decimal strings with a required currency code.

# Overview

> Inspect card payment attempts and refunds

<Note>
  Accept is in early access and subject to change. To request Accept access, contact [hi@natural.com](mailto:hi@natural.com).
</Note>

A card payment (`cpy_*`) records one attempt to pay a [payment intent](/guides/concepts/payment-intents). An intent can have multiple attempts. The `paymentIntent` relationship links each attempt to its intent.

[List card payments](/api-reference/card-payments/list-card-payments) to see attempts, or [get a card payment](/api-reference/card-payments/get-card-payment) to inspect one. Filter the list by `paymentIntentId` to see attempts for one intent. Both endpoints require `card_payments.read`.

## Payment status

* `processing`: the outcome is not yet confirmed.
* `succeeded`: the card payment was accepted. This does not mean funds have settled.
* `failed`: the attempt ended unsuccessfully. `failure` contains the available code, reason, and advice.

`settledAt` records when funds reached your wallet. It is null until settlement is recorded. The `cardPayment.succeeded` webhook confirms payment acceptance, not settlement.

The fee is assessed when the card is authorized, so it's always null on `cardPayment.created`. Read it from `cardPayment.succeeded`.

`brand` and `last4` identify the card when known. `channel` is `link` or `voice`. `receiptUrl` links to the receipt after a successful payment.

## Failure codes

For failed payments, `failure` contains a code, reason, and recommended action. These fields can be null when unavailable. New codes may be added.

Use `failure.advice` to decide what to do next: `doNotRetry`, `tryAgainLater`, or `confirmCardData`. Do not infer advice from the code alone.

| `failure.code` | Meaning |
| - | - |
| `genericDecline` | The card was declined. |
| `insufficientFunds` | The card has insufficient funds. |
| `limitExceeded` | The card's payment limit was exceeded. |
| `issuerUnavailable` | The card issuer is temporarily unavailable. |
| `processorError` | The processor could not complete the payment. |
| `cardExpired` | The card has expired. |
| `incorrectCardNumber` | The card number is incorrect. |
| `incorrectCvc` | The card security code is incorrect. |
| `incorrectAddress` | The billing address is incorrect. |
| `authenticationRequired` | The card requires authentication. |
| `cardNotSupported` | The card does not support this payment. |
| `cardInactiveOrClosed` | The card is inactive or closed. |
| `stopPayment` | The card issuer blocked this payment. |
| `cardLostStolen` | The card was reported lost or stolen. |
| `suspectedFraud` | The issuer suspects fraud. |
| `duplicateTransaction` | The issuer saw a duplicate payment. |

## Refunds

`refundedAmount` is the total returned by successful refunds. `refundableAmount` is the amount remaining after pending and successful refunds. It is zero unless the payment succeeded. Other refund restrictions may apply.

The `refunds` relationship includes up to 25 recent refunds, including pending and failed refunds. The totals include all refunds. [List refunds](/api-reference/refunds/list-refunds) with `cardPaymentId` for the full history.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.