{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["tabs","tab"]},"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":"recipe-authcapture-for-e-commerce","__idx":0},"children":["Recipe: Auth/capture for e-commerce"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"when-to-use-this-pattern","__idx":1},"children":["When to use this pattern"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You need to verify the card before fulfilling the order"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You ship physical goods and want to charge only when the order ships"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You want the option to adjust the amount (for example, partial shipments)"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"flow","__idx":2},"children":["Flow"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"https://files.modern-mermaid.live/images/1776277181092-mermaid-diagram-1776277181292.png","alt":"image"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-authorize-at-checkout","__idx":3},"children":["Step 1: Authorize at checkout"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When the customer places their order, authorize the full amount. This places a hold on the customer's card but does not transfer funds."]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"curl","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"curl -X POST \\\n  https://api.dev.paradisegateway.net/v1/transactions \\\n  -H \"Content-Type: application/json\" \\\n  -H \"APIKEY: YOUR-API-KEY\" \\\n  -d '{\n    \"type\": \"auth\",\n    \"amount\": 7500,\n    \"payment_method\": {\n      \"type\": \"card\",\n      \"card\": {\n        \"pan\": \"4111111111111111\",\n        \"expiry_month\": \"12\",\n        \"expiry_year\": \"2027\",\n        \"cvv\": \"123\",\n        \"cardholder_name\": \"Jane Smith\"\n      }\n    },\n    \"metadata\": {\n      \"order_id\": \"ORD-20260325-001\"\n    }\n  }'\n","lang":"shell"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Python","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"import os, requests\n\nAPI_KEY = os.environ[\"PARADISE_API_KEY\"]\nBASE = \"https://api.dev.paradisegateway.net\"\n\nauth_resp = requests.post(\n    f\"{BASE}/v1/transactions\",\n    headers={\"Content-Type\": \"application/json\", \"APIKEY\": API_KEY},\n    json={\n        \"type\": \"auth\",\n        \"amount\": 7500,\n        \"payment_method\": {\n            \"type\": \"card\",\n            \"card\": {\n                \"pan\": \"4111111111111111\",\n                \"expiry_month\": \"12\",\n                \"expiry_year\": \"2027\",\n                \"cvv\": \"123\",\n                \"cardholder_name\": \"Jane Smith\",\n            },\n        },\n        \"metadata\": {\"order_id\": \"ORD-20260325-001\"},\n    },\n)\nauth = auth_resp.json()\ntxn_id = auth[\"id\"]\nprint(f\"Authorized: {txn_id}, state: {auth['transaction_state']}\")\n","lang":"python"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"JavaScript","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"const API_KEY = process.env.PARADISE_API_KEY;\nconst BASE = \"https://api.dev.paradisegateway.net\";\n\nconst authResp = await fetch(`${BASE}/v1/transactions`, {\n  method: \"POST\",\n  headers: { \"Content-Type\": \"application/json\", \"APIKEY\": API_KEY },\n  body: JSON.stringify({\n    type: \"auth\",\n    amount: 7500,\n    payment_method: {\n      type: \"card\",\n      card: {\n        pan: \"4111111111111111\",\n        expiry_month: \"12\",\n        expiry_year: \"2027\",\n        cvv: \"123\",\n        cardholder_name: \"Jane Smith\",\n      },\n    },\n    metadata: { order_id: \"ORD-20260325-001\" },\n  }),\n});\nconst auth = await authResp.json();\nconsole.log(`Authorized: ${auth.id}, state: ${auth.transaction_state}`);\n","lang":"javascript"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"authorization-response","__idx":4},"children":["Authorization response"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"TRANSACTION-01KEW32V6YNV11T33XGDR7TGWC\",\n  \"type\": \"auth\",\n  \"amount\": 7500,\n  \"transaction_state\": \"authorized\",\n  \"response_status\": \"approved\",\n  \"response_code\": \"00\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Save the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," — you need it to capture or cancel later."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-capture-when-you-ship","__idx":5},"children":["Step 2: Capture when you ship"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When the order ships, capture the authorized amount (or a partial amount if you ship less)."]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"curl","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"curl -X POST \\\n  https://api.dev.paradisegateway.net/v1/transactions/TRANSACTION-01KEW32V6YNV11T33XGDR7TGWC/capture \\\n  -H \"Content-Type: application/json\" \\\n  -H \"APIKEY: YOUR-API-KEY\" \\\n  -d '{ \"amount\": 7500 }'\n","lang":"shell"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Python","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"cap_resp = requests.post(\n    f\"{BASE}/v1/transactions/{txn_id}/capture\",\n    headers={\"Content-Type\": \"application/json\", \"APIKEY\": API_KEY},\n    json={\"amount\": 7500},\n)\ncap = cap_resp.json()\nprint(f\"Captured: {cap['transaction_state']}\")\n","lang":"python"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"JavaScript","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"const capResp = await fetch(\n  `${BASE}/v1/transactions/${auth.id}/capture`,\n  {\n    method: \"POST\",\n    headers: { \"Content-Type\": \"application/json\", \"APIKEY\": API_KEY },\n    body: JSON.stringify({ amount: 7500 }),\n  }\n);\nconst cap = await capResp.json();\nconsole.log(`Captured: ${cap.transaction_state}`);\n","lang":"javascript"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3-handle-edge-cases","__idx":6},"children":["Step 3: Handle edge cases"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"cancel-if-the-order-is-canceled","__idx":7},"children":["Cancel if the order is canceled"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the customer cancels before shipment, void the authorization to release the hold immediately."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"curl -X POST \\\n  https://api.dev.paradisegateway.net/v1/transactions/TRANSACTION-01KEW32V6YNV11T33XGDR7TGWC/cancel \\\n  -H \"Content-Type: application/json\" \\\n  -H \"APIKEY: YOUR-API-KEY\" \\\n  -d '{ \"type\": \"cancel\", \"amount\": 7500 }'\n","lang":"shell"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"partial-shipment","__idx":8},"children":["Partial shipment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you ship only part of the order, capture only that amount. The remaining hold is released automatically."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"curl -X POST \\\n  https://api.dev.paradisegateway.net/v1/transactions/TRANSACTION-01KEW32V6YNV11T33XGDR7TGWC/capture \\\n  -H \"Content-Type: application/json\" \\\n  -H \"APIKEY: YOUR-API-KEY\" \\\n  -d '{ \"amount\": 4500 }'\n","lang":"shell"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"decision-tree","__idx":9},"children":["Decision tree"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"https://files.modern-mermaid.live/images/1776277225134-mermaid-diagram-1776277225352.png","alt":"image"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"best-practices","__idx":10},"children":["Best practices"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Capture promptly"]}," — authorization holds typically expire in 7–10 days. Capture before the hold expires."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Use metadata"]}," — attach your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order_id"]}," to the authorization so you can correlate transactions with orders."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Check AVS/CVV"]}," — review ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["avs_result_code"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cvv_result"]}," on the authorization response before fulfilling the order."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Idempotency"]}," — if your capture request times out, it is safe to retry; the API is idempotent for capture operations."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":11},"children":["Next steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/tutorials/payment-cookbook/handle-declined-transactions"},"children":["Handle declined transactions"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/how-tos/process-payments/handle-partial-capture"},"children":["Handle partial captures"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/how-tos/manage-transactions/cancel-auth"},"children":["Cancel an authorized transaction"]}]}]}]},"headings":[{"value":"Recipe: Auth/capture for e-commerce","id":"recipe-authcapture-for-e-commerce","depth":1},{"value":"When to use this pattern","id":"when-to-use-this-pattern","depth":2},{"value":"Flow","id":"flow","depth":2},{"value":"Step 1: Authorize at checkout","id":"step-1-authorize-at-checkout","depth":2},{"value":"Authorization response","id":"authorization-response","depth":3},{"value":"Step 2: Capture when you ship","id":"step-2-capture-when-you-ship","depth":2},{"value":"Step 3: Handle edge cases","id":"step-3-handle-edge-cases","depth":2},{"value":"Cancel if the order is canceled","id":"cancel-if-the-order-is-canceled","depth":3},{"value":"Partial shipment","id":"partial-shipment","depth":3},{"value":"Decision tree","id":"decision-tree","depth":2},{"value":"Best practices","id":"best-practices","depth":2},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"title":"Recipe: Auth/capture for e-commerce","shortTitle":"Auth/capture for e-commerce","intro":"Use a two-step authorization and capture flow to hold funds at checkout and capture only when you ship. This is the standard pattern for e-commerce merchants.","type":"tutorial","seo":{"title":""}},"lastModified":"2026-06-05T02:46:44.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/tutorials/payment-cookbook/auth-capture-ecommerce","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}