> For the complete documentation index, see [llms.txt](https://plexo.gitbook.io/rest-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://plexo.gitbook.io/rest-api/payments/payment-processing.md).

# Payment Processing

Use this guide as the action map for the Payments API. Each action has its own page with the intent, endpoint, and example flow so developers can jump directly to the operation they need.

## Overview

Payment processing is usually a sequence of small API actions:

1. Create a payment attempt.
2. Complete any required payer interaction.
3. Capture, cancel, refund, or search the payment depending on the business outcome.

The `PaymentDto.status`, `actions`, and `transactions` fields tell your integration what to do next. Store the Plexo `payment.id` with your order so later actions can target the same payment.

## Choose the Action

| Action                | Intent                                                                   | Endpoint                                                           | Guide                                                                                   |
| --------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
| Create a payment      | Start a new payment attempt for a checkout, POS, wallet, or backend flow | `POST /v1/payments`                                                | [Create a Payment](/rest-api/payments/payment-processing/create-payment.md)             |
| Authorize and capture | Reserve funds first, then settle later when fulfillment is ready         | `POST /v1/payments`, then `POST /v1/payments/{paymentId}/captures` | [Authorize and Capture](/rest-api/payments/payment-processing/authorize-and-capture.md) |
| Cancel a payment      | Stop an eligible payment before the refund path is the right action      | `POST /v1/payments/{paymentId}/cancellations`                      | [Cancel a Payment](/rest-api/payments/payment-processing/cancel-payment.md)             |
| Refund a payment      | Return captured or settled funds to the payer                            | `POST /v1/payments/{paymentId}/refunds`                            | [Refund a Payment](/rest-api/payments/payment-processing/refund-payment.md)             |
| Search payments       | Reconcile, filter, or inspect existing payments                          | `GET /v1/payments/query`                                           | [Search Payments](/rest-api/payments/payment-processing/search-payments.md)             |

## Example Flow

```
Create payment
    ↓
Read PaymentDto.status and PaymentDto.actions
    ↓
If manual capture is enabled, capture when ready to fulfill
    ↓
If the payment should stop before refund is appropriate, cancel it
    ↓
If funds were captured or settled and must be returned, refund it
    ↓
Search or retrieve the payment to reconcile final state
```

## Status and Action Signals

| Signal         | How to use it                                                                                                                                                 |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status`       | Drives your business state machine. Common values include `pending`, `authorized`, `approved`, `denied`, `cancelled`, `refunded`, and `partially-refunded`.   |
| `actions`      | Shows required payer steps, such as redirects or 3DS challenges. Do not treat the payment as final until the required actions are complete.                   |
| `transactions` | Records each operation performed against the payment, such as authorization, capture, cancellation, or refund. Use this for reconciliation and support tools. |
| `referenceId`  | Your idempotency and reconciliation anchor for the operation you are creating. Keep it unique per payment, capture, cancellation, or refund request.          |

## Developer Notes

* Use the smallest action page that matches the job you are doing instead of scanning a long guide.
* Persist Plexo identifiers and your own references together. Most follow-up actions require `payment.id`.
* Use callbacks for asynchronous status changes, then confirm final state with `GET /v1/payments/{paymentId}` or `GET /v1/payments/query`.
* Prefer cancellation while the payment is still cancellable.
* Use refunds after funds were captured or settled.

## Related Guides

* [Accepting Your First Payment](/rest-api/payments/first-payment.md)
* [PIX QR Payments for POS](/rest-api/pos-payments/pix-qr-pos.md)
* [3D Secure Integration Guide](/rest-api/payments/3ds-integration.md)
* [Verifying a Payment Method](/rest-api/payments/payment-method-verification.md)
* [Payment and Transaction Lifecycle](/rest-api/core-concepts/transaction-lifecycle.md)