{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/sidebars.yaml","api-docs-apis/openapi.yaml":"api-docs-apis/openapi.yaml"},"props":{"metadata":{"markdoc":{"tagList":["replay-openapi"]},"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":"recurring-payments","__idx":0},"children":["Recurring payments"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Recurring billing here is two fields on a normal transaction, not a separate"," ","product. There is no subscription resource, no plan, no customer object, and no"," ","recurring endpoint. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["You own the schedule"]},"; the gateway records the"," ","stored-credential relationship the card networks require and returns the"," ","identifiers that link one payment to the next."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Everything goes through ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/transactions"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"the-fields","__idx":1},"children":["The fields"]},{"$$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":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What it does"},"children":["What it does"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recurring"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Boolean. Marks the transaction as part of a recurring arrangement"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["initiator"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CUSTOMER"]}," when the cardholder is present, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MERCHANT"]}," when you bill without them"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recurring_details.sequence"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INITIAL"]}," for the first payment, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SUBSEQUENT"]}," for every one after"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recurring_details.initial_transaction_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," of the transaction that began the series"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recurring_details.initial_network_transaction_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The network's own identifier, when the series began somewhere else"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-the-initial-payment","__idx":2},"children":["Step 1: The initial payment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The first payment establishes the agreement. The cardholder is present and"," ","consenting, so it is customer-initiated."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"type\": \"SALE\",\n  \"amount\": 10000,\n  \"payment_method\": { \"type\": \"Card\", \"pan\": \"...\", \"expiry\": { \"month\": 1, \"year\": 2028 } },\n  \"initiator\": \"CUSTOMER\",\n  \"recurring\": true,\n  \"recurring_details\": { \"sequence\": \"INITIAL\" }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["From the response, keep two values:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}]}," — quote it as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["initial_transaction_id"]}," on every later payment."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["network_transaction_id"]}]}," — the card network's identifier for the agreement."," ","Store it; you need it if you ever move this series to another gateway."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-every-payment-after","__idx":3},"children":["Step 2: Every payment after"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Later payments are merchant-initiated: you are billing a card without the"," ","cardholder present. Send no CVV, because nobody is there to read one."]},{"$$mdtype":"Tag","name":"ReplayOpenApi","attributes":{"descriptionFile":"api-docs-apis/openapi.yaml","operationId":"createTransaction","exampleKey":"saleRecurringSubsequent","parameters":{},"options":{},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can send the card details again, as that example does, or send a"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/payments/save-and-reuse-a-payment-method"},"children":["saved token"]},". Either works; the token is"," ","the better choice because it keeps the number out of your systems."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"the-four-rules","__idx":4},"children":["The four rules"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The gateway enforces these and returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INVALID_ACTION"]}," when one is"," ","broken. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["The schema does not describe them"]},", so a generated SDK will not catch"," ","them for you — the request looks valid right up until the API rejects it."]},{"$$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":"Rule"},"children":["Rule"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Message when you break it"},"children":["Message when you break it"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recurring_details"]}," present means ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["initiator"]}," is required"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["initiator is required for recurring transactions"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sequence: INITIAL"]}," must use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["initiator: CUSTOMER"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["initiator must be CUSTOMER for the initial recurring transaction"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sequence: SUBSEQUENT"]}," needs ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["initial_transaction_id"]}," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["or"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["initial_network_transaction_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Either initial_transaction_id or initial_network_transaction_id is required for subsequent recurring transactions"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sequence: INITIAL"]}," must omit both of those"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["initial_transaction_id and initial_network_transaction_id must be omitted on the initial recurring transaction"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The second rule is the one that trips people. An initial recurring payment"," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["cannot"]}," be merchant-initiated: the cardholder has to be present to consent to"," ","their card being stored. If you are setting up a series without the customer"," ","there, you do not have an initial payment — you have a subsequent payment on an"," ","agreement made somewhere else, and it needs rule three."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"moving-a-series-from-another-gateway","__idx":5},"children":["Moving a series from another gateway"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the agreement started elsewhere, you have no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["initial_transaction_id"]}," to give,"," ","because the first payment was never a transaction here."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send the network's identifier instead, in"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recurring_details.initial_network_transaction_id"]},". That is what the field is"," ","for, and it is the only way to keep the stored-credential chain intact across a"," ","migration. Losing it usually shows up as a higher decline rate rather than an"," ","error."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-this-does-not-include","__idx":6},"children":["What this does not include"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Installments are out of scope."]}," The gateway processes recurring payments."," ","Fixed-instalment plans are not offered on the public API."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["No schedule, no retries, no dunning."]}," Nothing here runs on a timer. Your"," ","system decides when to bill and what to do when a payment fails."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["No customers, plans, or subscriptions."]}," Those resources do not exist. Your"," ","application owns them."]}]},{"$$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/save-and-reuse-a-payment-method"},"children":["Save and reuse a payment method"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/payments/handle-declines"},"children":["Handle declines"]}]},{"$$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":"Recurring payments","id":"recurring-payments","depth":1},{"value":"The fields","id":"the-fields","depth":2},{"value":"Step 1: The initial payment","id":"step-1-the-initial-payment","depth":2},{"value":"Step 2: Every payment after","id":"step-2-every-payment-after","depth":2},{"value":"The four rules","id":"the-four-rules","depth":2},{"value":"Moving a series from another gateway","id":"moving-a-series-from-another-gateway","depth":2},{"value":"What this does not include","id":"what-this-does-not-include","depth":2},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"title":"Recurring payments","shortTitle":"Recurring","intro":"Billing a stored card on a schedule. Two fields on an ordinary transaction do it, and four rules decide whether the request is accepted.","type":"how-to","seo":{"title":""}},"lastModified":"2026-09-17T08:54:39.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/payments/recurring-payments","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}