> 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/core-concepts/transaction-lifecycle.md). # Payment and Transaction Lifecycle ## Overview A `PaymentDto` is the top-level record for a payment attempt. Its `transactions` array records the individual operations performed on that payment, such as a purchase, an authorization, a capture, a cancellation, or a refund. Use the payment `status` for the current overall state. Use `transactions` when you need the detailed history of what happened during processing. ## Canonical payment statuses These are the current public payment status values exposed by the backend. | Status | Meaning | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `created` | The payment object was created and processing has not completed yet. | | `pending` | The processor or a customer step is still in progress. | | `authorized` | Funds were authorized but not yet captured. | | `approved` | Funds were successfully captured, or the purchase completed in one step. | | `denied` | The payment was declined. | | `cancelled` | An eligible payment was cancelled. For cards, this can be an authorization void or an approved purchase cancellation; for non-card payments, it can also apply to pending payments. | | `refunded` | The full captured amount was refunded. | | `partially-refunded` | Part of the captured amount was refunded. | | `expired` | The authorization expired before capture. | | `failed` | Processing failed for a technical or processor-side reason. | ## Canonical transaction statuses These are the current transaction status values used in payment transaction records. | Status | Meaning | | ---------- | ------------------------------------------------------------ | | `created` | The transaction record was created. | | `pending` | The transaction is still being processed. | | `approved` | The transaction completed successfully. | | `denied` | The transaction was declined. | | `expired` | The transaction expired before completion. | | `failed` | The transaction failed due to a technical or upstream error. | ## Transaction result codes `transactions[].resultCode` is a string so clients can preserve leading zeros, but newly written transaction result codes contain ASCII digits only. When a transaction source returns a nonnumeric result code, Plexo writes its numeric result code in `resultCode` and preserves the exact source value in `sourceResultCode`. Already-numeric provider and switch codes remain source-specific. Do not infer a universal status-to-code table from `resultCode`; use the transaction `status` for its business meaning. This is forward-looking behavior. Historical payments can retain a nonnumeric `resultCode` and omit `sourceResultCode`; Plexo does not backfill or rewrite those records. ### 3DS-required result mapping When a card payment requires 3DS authentication, Plexo returns a pending transaction with `resultCode` set to `2101` and preserves the flow-specific source value `threeds-required` in `sourceResultCode`. Use the payment `status` and `actions` as the source of truth for pending-state and redirect handling. | Transaction context | Source result | `status` | `resultCode` | `sourceResultCode` | | --------------------------- | ------------------ | --------- | -----------: | ------------------ | | 3DS authentication required | `threeds-required` | `pending` | `2101` | `threeds-required` | ### PIX PagBrasil callback result mapping For PIX callbacks from PagBrasil, the source result is preserved in `sourceResultCode` and the newly written `resultCode` is as follows: | Callback context | Source result | `resultCode` | `sourceResultCode` | | ----------------------------- | ------------- | -----------: | ------------------ | | Approved purchase | `A` | `0` | `A` | | Approved refund or chargeback | `P` or `C` | `0` | source value | | Approved cancellation | `R` | `0` | `R` | | Rejected purchase | `R` | `10` | `R` | | Rejected refund | `J` | `10` | `J` | | Failed operation | `F` | `999` | `F` | ## Common flows ### Purchase flow Use `POST /v1/payments` with `capture.method = automatic` when you want a single-step purchase. ```json { "merchantId": 12345, "referenceId": "order-1001", "invoiceNumber": "1001", "amount": { "total": 100.00, "currency": "UYU" }, "paymentMethod": { "source": "card", "card": { "number": "4111111111111111", "expMonth": 12, "expYear": 2028, "cvc": "123", "cardholder": { "firstName": "Test", "lastName": "User" } } }, "browserDetails": { "ipAddress": "203.0.113.10", "userAgent": "Mozilla/5.0" }, "capture": { "method": "automatic" } } ``` Typical status path: ``` created -> pending -> approved ``` If the processor declines the request or a customer step fails, the payment can end in `denied` or `failed` instead. ### Authorization and later capture Use `POST /v1/payments` with `capture.method = manual` when you want to authorize first and capture later. ```json { "merchantId": 12345, "referenceId": "order-2001", "invoiceNumber": "2001", "amount": { "total": 250.00, "currency": "UYU" }, "paymentMethod": { "source": "card", "card": { "number": "4111111111111111", "expMonth": 12, "expYear": 2028, "cvc": "123", "cardholder": { "firstName": "Test", "lastName": "User" } } }, "browserDetails": { "ipAddress": "203.0.113.10", "userAgent": "Mozilla/5.0" }, "capture": { "method": "manual" } } ``` Typical status path after payment creation: ``` created -> pending -> authorized ``` Capture the authorized payment later with: ``` POST /v1/payments/{paymentId}/captures ``` After a successful capture, the payment moves to `approved`. ### Payment cancellation Cancel an eligible payment with: ``` POST /v1/payments/{paymentId}/cancellations ``` This route is for card payments in `authorized` or `approved` state, and for non-card payments in `pending` or `approved` state. After a successful cancellation, the payment moves to `cancelled`. Typical status path: ``` authorized -> cancelled approved -> cancelled pending -> cancelled ``` Example cancellation request: ```json { "referenceId": "cancel-order-2001", "reason": "order-cancelled", "description": "Order cancelled before shipment" } ``` Use cancellation to release an authorization hold or stop an eligible payment before the processor no longer allows cancellation. If cancellation is rejected because the payment is already settled or otherwise incompatible, use the refund route instead. ### Refund after capture Refund a captured payment with: ``` POST /v1/payments/{paymentId}/refunds ``` After a partial refund, the payment status becomes `partially-refunded`. After the full captured amount is refunded, the payment status becomes `refunded`. Refunds apply after capture or settlement. Use cancellation only while the payment is still in a state where the backend and processor allow cancellation. ### Payment-method verification Use `POST /v1/payments/verify` when you need to validate a card or token without creating a normal charge flow. The backend performs a small authorization and then triggers a cancellation flow for that verification attempt. Treat this route as a validation operation, not a settled payment. ## How to read a payment object When you retrieve a payment, read it in this order: 1. Check `status` for the overall current state. 2. Review `transactions` to see the operations that produced that state. 3. Inspect `actions` when the payer must complete a redirect or 3DS step. Example: ```json { "id": "550e8400e29b41d4a716446655440000", "referenceId": "order-1001", "status": "approved", "amount": { "total": 100.00, "currency": "UYU" }, "transactions": [ { "id": "660e8400-e29b-41d4-a716-446655440001", "type": "purchase", "status": "approved" } ] } ``` In this example, the payment is complete because the payment `status` is `approved` and the recorded transaction was an approved `purchase`. ## Related resources * [Payment Processing Guide](/rest-api/payments/payment-processing.md) * [Accepting Your First Payment](/rest-api/payments/first-payment.md) * [Verifying a Payment Method](/rest-api/payments/payment-method-verification.md) * [Error Codes Reference](/rest-api/reference/error-codes.md)