{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Reefpay Docs","description":"Reefpay is the groundbreaking payment gateway that lets you integrate with the future of payments."},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"transaction-lifecycle","__idx":0},"children":["Transaction lifecycle"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A transaction is not finished when the response arrives. It gets authorized,"," ","possibly captured, gathered into a batch, settled, and — for ACH — it can still"," ","be returned days later."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Knowing which stage a transaction is in tells you what you can still do to it."," ","Most of the rules on this page reduce to one question: has it settled yet?"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"---\nconfig:\n theme: 'neutral'\n---\nflowchart LR\n A[Request] --> B{result}\n B -->|DECLINED or ERROR| C[Finished]\n B -->|APPROVED| D[Authorized]\n D -->|SALE| E[In a batch]\n D -->|AUTH| F[Awaiting capture]\n F -->|capture| E\n F -->|void| C\n E -->|batch closes| G[Settled]\n G -->|refund| H[Refunded]\n G -->|ACH only| I[Returned]\n","diagramHtml":"

DECLINED or ERROR

APPROVED

SALE

AUTH

capture

void

batch closes

refund

ACH only

Request

result

Finished

Authorized

In a batch

Awaiting capture

Settled

Refunded

Returned

","diagramHtmlDark":"

DECLINED or ERROR

APPROVED

SALE

AUTH

capture

void

batch closes

refund

ACH only

Request

result

Finished

Authorized

In a batch

Awaiting capture

Settled

Refunded

Returned

"},"children":["---\nconfig:\n theme: 'neutral'\n---\nflowchart LR\n A[Request] --> B{result}\n B -->|DECLINED or ERROR| C[Finished]\n B -->|APPROVED| D[Authorized]\n D -->|SALE| E[In a batch]\n D -->|AUTH| F[Awaiting capture]\n F -->|capture| E\n F -->|void| C\n E -->|batch closes| G[Settled]\n G -->|refund| H[Refunded]\n G -->|ACH only| I[Returned]\n"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"the-stages","__idx":1},"children":["The stages"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Stage"},"children":["Stage"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"How you know"},"children":["How you know"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What you can do"},"children":["What you can do"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Authorized"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["result"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["APPROVED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Capture it, or void it"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Awaiting capture"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AUTH"]}," and no capture references it"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Capture, partially capture, or void"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["In a batch"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["batch_id"]}," is not null"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Void it, until the batch closes"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Settled"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["is_settled"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Refund it"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Returned"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["is_returned"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Nothing. ACH only"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["batch_id"]}," is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["null until the transaction reaches a batch"]},", which happens when"," ","the settlement request gets to the processor rather than at the moment you are"," ","approved. A null ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["batch_id"]}," on a fresh sale is normal."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"each-step-is-its-own-transaction","__idx":2},"children":["Each step is its own transaction"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is the part that surprises people coming from other gateways."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A capture does not update the authorization. It creates a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["new"]}," transaction"," ","with its own ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]},", a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}," of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CAPTURE"]},", and a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reference_transaction_id"]}," ","pointing back at the authorization. The same is true of a cancel and a refund."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["So a single payment can be several records:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"TRANSACTION-…A type: AUTH reference_transaction_id: null\nTRANSACTION-…B type: CAPTURE reference_transaction_id: TRANSACTION-…A\nTRANSACTION-…C type: REFUND reference_transaction_id: TRANSACTION-…B\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you reconcile, follow ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reference_transaction_id"]}," rather than expecting one"," ","row per payment."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"three-enums-describe-a-transaction-type","__idx":3},"children":["Three enums describe a transaction type"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["They are not interchangeable, and picking the wrong one is a common source of"," ","400s and empty report results."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Where"},"children":["Where"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Values"},"children":["Values"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Creating a transaction"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SALE"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AUTH"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PAYOUT"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["On a response, and on the report filter"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SALE"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AUTH"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INCREMENTAL_AUTH"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PAYOUT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REFUND"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CANCEL"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CAPTURE"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["As the discriminator on a cancel or refund body"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VOID"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REFUND"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["A voided payment comes back as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CANCEL"]},", never ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VOID"]},"."]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VOID"]}," is the word you"," ","send; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CANCEL"]}," is the word you read. Filtering a report on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VOID"]}," returns a"," ","server error — see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/after-the-payment/find-and-report-on-transactions"},"children":["Find and report on transactions"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INCREMENTAL_AUTH"]}," appears only on responses. There is no way to create one"," ","through the public API."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"approved-is-not-always-final","__idx":4},"children":["Approved is not always final"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A card decline arrives in the response. An ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["ACH return does not"]}," — it can show"," ","up days after settlement, when the receiving bank rejects the entry."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["is_returned"]}," carries it, and it is worth reading alongside ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["is_settled"]}," rather"," ","than instead of it, because a returned transaction has usually settled first."," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/payments/accept-an-ach-payment"},"children":["Accept an ACH payment"]}," covers the return"," ","fields and their quirks."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There are no webhooks, so finding out means polling"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/after-the-payment/find-and-report-on-transactions"},"children":["the reporting endpoints"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":5},"children":["Next steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/after-the-payment/cancel-void-and-refund"},"children":["Cancel, void, and refund"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/after-the-payment/batches-and-settlement"},"children":["Batches and settlement"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/after-the-payment/find-and-report-on-transactions"},"children":["Find and report on transactions"]}]}]}]},"headings":[{"value":"Transaction lifecycle","id":"transaction-lifecycle","depth":1},{"value":"The stages","id":"the-stages","depth":2},{"value":"Each step is its own transaction","id":"each-step-is-its-own-transaction","depth":2},{"value":"Three enums describe a transaction type","id":"three-enums-describe-a-transaction-type","depth":2},{"value":"Approved is not always final","id":"approved-is-not-always-final","depth":2},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"title":"Transaction lifecycle","shortTitle":"Lifecycle","intro":"What happens to a payment after the API returns, from authorization through settlement, and which fields tell you where it is.","type":"overview","seo":{"title":""}},"lastModified":"2026-09-17T09:08:13.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/after-the-payment/transaction-lifecycle","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}