{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/sidebars.yaml","api-docs-apis/openapi.yaml":"api-docs-apis/openapi.yaml"},"props":{"metadata":{"markdoc":{"tagList":["replay-openapi","openapi-response-sample"]},"type":"markdown"},"seo":{"title":"Reefpay Docs","description":"Reefpay is the groundbreaking payment gateway that lets you integrate with the future of payments."},"dynamicMarkdocComponents":["openapi"],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"authorize-and-capture","__idx":0},"children":["Authorize and capture"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An authorization reserves funds on a card without moving them. A capture moves"," ","them. Splitting the two is the right shape whenever you charge before you know"," ","the final amount, or before you can deliver."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The usual cases are shipping physical goods, orders that may be partly out of"," ","stock, and anything where the total can change between checkout and fulfillment."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"before-you-start","__idx":1},"children":["Before you start"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Api-Key"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Client-Id"]}," — see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/get-started/authentication"},"children":["Authentication"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A processor integration configured for cards"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-authorize","__idx":2},"children":["Step 1: Authorize"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/transactions"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}," set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AUTH"]},". The request is identical to a"," ","sale apart from that one field."]},{"$$mdtype":"Tag","name":"ReplayOpenApi","attributes":{"descriptionFile":"api-docs-apis/openapi.yaml","operationId":"createTransaction","exampleKey":"authWithCard","parameters":{},"options":{},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Keep the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," from the response. Every later step quotes it in the URL."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-capture","__idx":3},"children":["Step 2: Capture"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/transactions/{id}/capture"]},", where ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{id}"]}," is the authorization's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]},"."]},{"$$mdtype":"Tag","name":"ReplayOpenApi","attributes":{"descriptionFile":"api-docs-apis/openapi.yaml","operationId":"captureTransaction","exampleKey":"captureCard","parameters":{},"options":{},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The body is small: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]}," is required, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tip"]}," is optional."," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["There is no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}," field."]}," ","It was removed from this request, and sending one is a common carry-over from"," ","older integrations."]},{"$$mdtype":"Tag","name":"OpenApiResponseSample","attributes":{"descriptionFile":"api-docs-apis/openapi.yaml","operationId":"captureTransaction","exampleKey":"captureCard","responseSamplesResolved":[{"lang":"json","title":"200 application/json","source":"{\n  \"id\": \"TRANSACTION-01KEW35B8QP4M2X9YHFT0KDN47\",\n  \"reference_transaction_id\": \"TRANSACTION-01KEW32V6YNV11T336VEDKL123\",\n  \"type\": \"CAPTURE\",\n  \"result\": \"APPROVED\",\n  \"client_id\": \"CLIENT-01KFDKXMQ637EKEAY410MSQSXB\",\n  \"client_dba\": \"Acme Jewelry\",\n  \"integrations\": [\n    \"TSYS\"\n  ],\n  \"response_code\": \"00\",\n  \"response_description\": \"Approved\",\n  \"batch_id\": \"BATCH-01KEW32V6YNV11T33XGDR7TGWC\",\n  \"is_settled\": false,\n  \"time_created\": \"2026-07-15T16:08:23Z\",\n  \"amount\": 10000,\n  \"tip\": 0,\n  \"currency\": \"USD\",\n  \"payment_method\": {\n    \"type\": \"CARD\",\n    \"truncated_pan\": \"****-****-****-5439\",\n    \"payment_token\": \"PAYMENT_TOKEN-01KFDKXMQ637EKEAY410MSQSXB\",\n    \"expiry\": null,\n    \"first_name\": \"John\",\n    \"last_name\": \"Doe\",\n    \"entry_method\": \"keyed\",\n    \"auth_code\": \"123456\",\n    \"retrieval_reference_number\": \"000000603076\",\n    \"card_type\": \"UNKNOWN\",\n    \"card_brand\": \"Visa\",\n    \"cvv_result_code\": \"M\"\n  },\n  \"initiator\": \"CUSTOMER\",\n  \"network_transaction_id\": \"MCC1234567890\",\n  \"metadata\": {\n    \"order_id\": \"ORD-10434\",\n    \"sales_channel\": \"web\",\n    \"customer_reference\": \"cust-8891\"\n  }\n}"},{"lang":"json","title":"400 application/json","source":"{\n  \"error_code\": \"INVALID_REQUEST_DATA\",\n  \"error_message\": \"The API request contains invalid data.\",\n  \"details\": {\n    \"amount\": \"Invalid amount\",\n    \"payment_method.pan\": \"Malformed PAN\"\n  },\n  \"source\": {\n    \"system\": \"TSYS\",\n    \"code\": \"13\",\n    \"message\": \"Invalid amount\"\n  }\n}"},{"lang":"json","title":"401 application/json","source":"{\n  \"error_code\": \"NOT_AUTHENTICATED\",\n  \"error_message\": \"Access credentials missing or invalid.\",\n  \"details\": null,\n  \"source\": {\n    \"system\": null,\n    \"code\": null,\n    \"message\": null\n  }\n}"},{"lang":"json","title":"403 application/json","source":"{\n  \"error_code\": \"UNAUTHORIZED_ACTION\",\n  \"error_message\": \"Requested action is unavailable or forbidden.\",\n  \"details\": null,\n  \"source\": {\n    \"system\": null,\n    \"code\": null,\n    \"message\": null\n  }\n}"},{"lang":"json","title":"404 application/json","source":"{\n  \"error_code\": \"RESOURCE_NOT_FOUND\",\n  \"error_message\": \"Resource not found.\",\n  \"details\": null,\n  \"source\": {\n    \"system\": null,\n    \"code\": null,\n    \"message\": null\n  }\n}"},{"lang":"json","title":"409 application/json","source":"{\n  \"error_code\": \"DUPLICATE_ACTION\",\n  \"error_message\": \"Duplicate action requested.\",\n  \"details\": null,\n  \"source\": {\n    \"system\": \"TSYS\",\n    \"code\": \"12\",\n    \"message\": \"Invalid transaction\"\n  }\n}"},{"lang":"json","title":"500 application/json","source":"{\n  \"error_code\": \"SYSTEM_ERROR\",\n  \"error_message\": \"Internal system error.\",\n  \"details\": null,\n  \"source\": {\n    \"system\": \"TSYS\",\n    \"code\": \"96\",\n    \"message\": \"System malfunction\"\n  }\n}"},{"lang":"json","title":"502 application/json","source":"{\n  \"error_code\": \"DOWNSTREAM_ERROR\",\n  \"error_message\": \"Downstream service returned invalid or unexpected response.\",\n  \"details\": null,\n  \"source\": {\n    \"system\": \"VERICHECK\",\n    \"code\": \"502\",\n    \"message\": \"Bad Gateway\"\n  }\n}"}]},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Three things about that response surprise people."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["The capture is its own transaction"]},", with its own ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," and a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}," of"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CAPTURE"]},". It is not the authorization updated in place."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reference_transaction_id"]}," points back at the authorization."]}," That is the"," ","link between the two."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expiry"]}," is null."]}," Card expiry is not echoed on a capture response."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["batch_id"]}," is populated now, so the funds settle at the next batch close."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"capture-less-than-you-authorized","__idx":4},"children":["Capture less than you authorized"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send a smaller ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]},". This is the normal way to handle an order that ships"," ","short, or a final total below the estimate."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"amount\": 7500\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You cannot capture ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["more"]}," than you authorized. If the total has gone up, the"," ","authorization no longer covers it — release it and authorize the new amount."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"release-a-hold-you-will-not-use","__idx":5},"children":["Release a hold you will not use"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the order is canceled before you ship, void the authorization so the"," ","cardholder's funds are freed rather than left on hold until the issuer expires"," ","them."]},{"$$mdtype":"Tag","name":"ReplayOpenApi","attributes":{"descriptionFile":"api-docs-apis/openapi.yaml","operationId":"cancelTransaction","exampleKey":"voidTransaction","parameters":{},"options":{},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A void takes only ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]},". It always releases the full amount, so there is no"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]}," field to send."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/after-the-payment/cancel-void-and-refund"},"children":["Cancel, void, and refund"]}," covers"," ","the difference between voiding and refunding, and which one applies when."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-long-a-hold-lasts","__idx":6},"children":["How long a hold lasts"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An uncaptured authorization does not last forever. The issuer decides how long,"," ","and it varies by card brand and issuer — commonly a few days to about a month."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The gateway does not expire authorizations on its own, and it does not notify you"," ","when an issuer does. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["If you are not going to capture, void explicitly"]}," rather"," ","than letting the hold lapse."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":7},"children":["Next steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/payments/add-a-tip"},"children":["Add a tip"]}]},{"$$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/payments/handle-declines"},"children":["Handle declines"]}]}]}]},"headings":[{"value":"Authorize and capture","id":"authorize-and-capture","depth":1},{"value":"Before you start","id":"before-you-start","depth":2},{"value":"Step 1: Authorize","id":"step-1-authorize","depth":2},{"value":"Step 2: Capture","id":"step-2-capture","depth":2},{"value":"Capture less than you authorized","id":"capture-less-than-you-authorized","depth":2},{"value":"Release a hold you will not use","id":"release-a-hold-you-will-not-use","depth":2},{"value":"How long a hold lasts","id":"how-long-a-hold-lasts","depth":2},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"title":"Authorize and capture","shortTitle":"Auth and capture","intro":"Place a hold on a card now, take the money when you ship. Covers full captures, partial captures, and releasing a hold you no longer need.","type":"how-to","seo":{"title":""}},"lastModified":"2026-09-17T08:54:39.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/payments/authorize-and-capture","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}