{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["img"]},"type":"markdown"},"seo":{"title":"Reefpay Docs","description":"Reefpay is the groundbreaking payment gateway that lets you integrate with the future of payments.","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"about-the-transaction-lifecycle","__idx":0},"children":["About the transaction lifecycle"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"transaction-states","__idx":1},"children":["Transaction states"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A transaction progresses through states that reflect where it is in the authorization and settlement process."]},{"$$mdtype":"Tag","name":"Image","attributes":{"src":"https://files.modern-mermaid.live/images/1776270187157-mermaid-diagram-1776270187339.png","alt":"Transaction lifecycle","framed":false,"withLightbox":true,"className":"transaction-lifecycle","width":"auto","height":"auto"},"children":[]},{"$$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":{"align":"left","data-label":"State (Status)"},"children":["State (Status)"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"How it is reached"},"children":["How it is reached"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["authorized"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Funds are held on the person's account but not yet transferred to the merchant."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["A successful ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sale"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["auth"]},", or ACH transaction returns this state."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["declined"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The issuing bank or processor rejected the transaction."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The processor returns a non-approval response code."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["captured"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The authorized amount is marked for settlement."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/transactions/{id}/capture"]}," on an authorized transaction. For ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["card_sale"]},", capture happens automatically."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["canceled"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The transaction is voided before settlement. No funds transfer."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/transactions/{id}/cancel"]}," with type ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancel"]}," on an authorized or captured transaction before batch closure."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["settled"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Funds have been transferred from the person's account to the merchant's account."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The batch containing the transaction closes and clears through the processor network."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["refunded"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Funds have been returned to the person after settlement."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/transactions/{id}/cancel"]}," with type ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["refund"]}," on a settled transaction."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"transaction-lifecycle","__idx":2},"children":["Transaction lifecycle"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Card transactions follow a two-phase process: authorization and settlement."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"phase-1-authorization","__idx":3},"children":["Phase 1: Authorization"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you create a transaction, the processor communicates with the card network and issuing bank to verify funds and approve the payment. A successful authorization places a hold on the person's account for the approved amount."]},{"$$mdtype":"Tag","name":"Image","attributes":{"src":"https://files.modern-mermaid.live/images/1776270109697-mermaid-diagram-1776270109871.png","alt":"Transaction lifecycle","framed":false,"withLightbox":true,"className":"transaction-lifecycle","width":"auto","height":"auto"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["At this point, the transaction is either ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["authorized"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["declined"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"phase-2-settlement","__idx":4},"children":["Phase 2: Settlement"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Authorized transactions accumulate in a batch. When the batch closes (either on schedule or manually), the processor submits the batch to the card network for clearing, and funds transfer from the issuing bank to the merchant's acquiring bank."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more information, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/concepts/transactions/batch-settlement"},"children":["About batch settlement"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"sale-vs-authorization","__idx":5},"children":["Sale vs. authorization"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The lifecycle differs depending on whether you use a one-step sale or a two-step authorization."]},{"$$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":{"align":"left","data-label":"Flow"},"children":["Flow"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Steps"},"children":["Steps"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Use case"},"children":["Use case"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["One-step (sale)"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/transactions"]}," with type ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sale"]}," → authorized → settled"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Immediate fulfillment (digital goods, in-person retail)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Two-step (auth + capture)"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/transactions"]}," with type ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["auth"]}," → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/transactions/{id}/capture"]}," → settled"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Delayed fulfillment (shipping, pre-orders)"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For a detailed comparison, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/concepts/transactions/sale-vs-auth"},"children":["About sale vs. authorization"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"ach-transaction-lifecycle","__idx":6},"children":["ACH transaction lifecycle"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["ACH transactions follow a different timeline because the Automated Clearing House (ACH) network processes in batches rather than in real time."]},{"$$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":{"align":"left","data-label":"Event"},"children":["Event"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Timeline"},"children":["Timeline"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Transaction submitted"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Immediate API response with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["authorized"]}," state"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Batch sent to ACH network"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Next business day"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Funds settled"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["2–3 business days"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Returns possible"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Up to 60 days"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["ACH transactions can be returned after settlement (for example, due to insufficient funds or a closed account). For more information, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/concepts/transactions/ach-accounts"},"children":["About ACH/bank account payments"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"cancels-and-refunds","__idx":7},"children":["Cancels and refunds"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The action you take to reverse a transaction depends on its current state."]},{"$$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":{"align":"left","data-label":"Current state"},"children":["Current state"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Action"},"children":["Action"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Result"},"children":["Result"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["authorized"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["captured"]}," (before batch closure)"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Cancel (void)"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Transaction moves to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["canceled"]},". No funds transfer."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["settled"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Refund"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["A new credit transaction returns funds to the person."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more information, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/concepts/transactions/cancels-and-refunds"},"children":["About cancels and refunds"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"checking-transaction-state","__idx":8},"children":["Checking transaction state"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retrieve the current state of any transaction with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/transactions/{id}"]},". The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction_state"]}," field reflects the current lifecycle position."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"curl -X GET \\\n  https://api.dev.paradisegateway.net/v1/transactions/TRANSACTION-ID \\\n  -H \"APIKEY: YOUR-API-KEY\"\n","lang":"shell"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Replace ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRANSACTION-ID"]}," with the transaction identifier from the original response."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"further-reading","__idx":9},"children":["Further reading"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/concepts/transactions/sale-vs-auth"},"children":["About sale vs. authorization"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/concepts/transactions/cancels-and-refunds"},"children":["About cancels and refunds"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/concepts/transactions/batch-settlement"},"children":["About batch settlement"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/concepts/transactions/ach-accounts"},"children":["About ACH/bank account payments"]}]}]}]},"headings":[{"value":"About the transaction lifecycle","id":"about-the-transaction-lifecycle","depth":1},{"value":"Transaction states","id":"transaction-states","depth":2},{"value":"Transaction lifecycle","id":"transaction-lifecycle","depth":2},{"value":"Phase 1: Authorization","id":"phase-1-authorization","depth":3},{"value":"Phase 2: Settlement","id":"phase-2-settlement","depth":3},{"value":"Sale vs. authorization","id":"sale-vs-authorization","depth":2},{"value":"ACH transaction lifecycle","id":"ach-transaction-lifecycle","depth":2},{"value":"Cancels and refunds","id":"cancels-and-refunds","depth":2},{"value":"Checking transaction state","id":"checking-transaction-state","depth":2},{"value":"Further reading","id":"further-reading","depth":2}],"frontmatter":{"title":"About the transaction lifecycle","shortTitle":"Transaction lifecycle","intro":"Every transaction in{% $env.PUBLIC_BRAND_NAME %} moves through a series of states from creation to settlement. Understanding these states helps you build correct payment workflows.","type":"overview","seo":{"title":""}},"lastModified":"2026-06-05T02:46:44.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/concepts/transactions/transaction-lifecycle","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}