{ "version": 1, "workflows": { "accept-apple-pay": { "workflowId": "accept-apple-pay", "domain": "payments", "title": "Validate an Apple Pay merchant session, then run a sale with the wallet token.", "summary": "Validate an Apple Pay merchant session, then run a sale with the wallet token.", "stepCount": 4, "gotchas": [], "operationIds": [ "applePaySessions", "payment" ], "workflowRefs": [], "keywords": [ "duhdzjhgyy", "https", "gateway", "com", "paymentservices", "startsession", "start", "jane", "orderref6543", "order", "ref6543", "large", "pepperoni", "pizza", "usd", "idempotencykey" ], "diagram": { "actors": [ { "id": "cardholder", "name": "Cardholder", "type": "human", "description": "Customer who authorizes the charge in Apple Pay on their device." }, { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "Calls the Payroc API on the cardholder's behalf." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." }, { "id": "apple", "name": "Apple Pay", "type": "external-system", "description": "Issues the merchant session and the encrypted payment data via the Apple Pay JS API / PassKit; not directly callable through this API.\n" } ], "steps": [ { "title": "Register Apple Pay domain", "label": "domain registration", "badge": "domain registration · not REST", "actorId": "merchant", "actorToId": "payroc-gateway" }, { "title": "Start Apple Pay session", "label": "session validation request", "badge": "REST · session validation request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "applePaySessions" }, { "title": "Authorize with Apple Pay", "label": "Apple Pay authorization", "badge": "Apple Pay authorization · not REST", "actorId": "cardholder", "actorToId": "apple" }, { "title": "Run Apple Pay sale", "label": "wallet sale request", "badge": "REST · wallet sale request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "payment" } ] } }, "accept-google-pay": { "workflowId": "accept-google-pay", "domain": "payments", "title": "Run a sale using an encrypted Google Pay token.", "summary": "Run a sale using an encrypted Google Pay token.", "stepCount": 2, "gotchas": [ "paymentMethod.type must be `digitalWallet` and paymentMethod.serviceProvider must be `google` (not `apple`). encryptedData is the hex-encoded token from Google Pay, not a card number or secure token.", "This is a sale, so leave autoCapture at its default of `true` (a pre-auth would send `false` and capture later). processAsSale immediately settles and then blocks adjustment; leave it `false` unless immediate settlement is intended.", "Variants (web vs in-app) differ only in how the client acquires the Google Pay token client-side; both submit the identical payment request with channel `web`. Do not split this into separate flows." ], "operationIds": [ "payment" ], "workflowRefs": [], "keywords": [ "web", "pos", "moto", "jane", "orderref6543", "order", "ref6543", "pizza", "doe", "dinner", "usd", "f67890", "abcdef", "idempotencykey", "idempotency", "key" ], "diagram": { "actors": [ { "id": "cardholder", "name": "Cardholder", "type": "human", "description": "Cardholder who authorizes the payment through Google Pay." }, { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "Website or mobile app that calls the Payroc API on the customer's behalf." }, { "id": "google-pay", "name": "Google Pay API", "type": "external-system", "description": "Issues the encrypted payment token client-side; not called by these steps." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface this step calls." }, { "id": "processor", "name": "Payment processor", "type": "external-system", "description": "Downstream processor behind the gateway; not directly callable." } ], "steps": [ { "title": "Authorize with Google Pay", "label": "Google Pay authorization", "badge": "Google Pay authorization · not REST", "actorId": "cardholder", "actorToId": "google-pay" }, { "title": "Run Google Pay sale", "label": "wallet sale request", "badge": "REST · wallet sale request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "payment" } ] } }, "add-attachment": { "workflowId": "add-attachment", "domain": "attachments", "title": "Upload a document to a processing account, then optionally retrieve it.", "summary": "Upload a document to a processing account, then optionally retrieve it.", "stepCount": 2, "gotchas": [ "The upload step is NOT JSON. It accepts a file upload, so the request Content-Type must be multipart/form-data, carrying an `attachment` object (only `type` is required) plus the binary `file`. Only one attachment per request; each file must be uncompressed and under 50 MB.", "The upload response returns an `attachmentId` at the top level and an `uploadStatus` of `pending`, `accepted`, or `rejected`. A 201 means the request was received, not that the file is accepted — poll the retrieve step to observe `uploadStatus` transition to `accepted`.", "Retrieval uses the standalone `GET /attachments/{attachmentId}` operation (the Attachments domain), not a processing-account-scoped path. It returns metadata about the file, never the file bytes themselves." ], "operationIds": [ "createProcessingAccountAttachment", "getAttachment" ], "workflowRefs": [], "keywords": [ "personalidentification", "personal", "identification", "passport", "lease", "agreement", "processingaccountid", "idempotencykey", "idempotency", "key", "attachmenttype", "type", "attachmentdescription", "description", "uuid", "bankingevidence" ], "diagram": { "actors": [ { "id": "integrator", "name": "Integrator", "type": "client", "description": "Uploads and retrieves the supporting document; the only API caller in this workflow." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." } ], "steps": [ { "title": "Upload attachment", "label": "upload document", "badge": "REST · upload document", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "createProcessingAccountAttachment" }, { "title": "Get attachment", "label": "check upload status", "badge": "REST · check upload status", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "getAttachment" } ] } }, "add-processing-account": { "workflowId": "add-processing-account", "domain": "boarding", "title": "Create a processing account on a merchant platform, then optionally remind the merchant to sign.", "summary": "Create a processing account on a merchant platform, then optionally remind the merchant to sign.", "stepCount": 4, "gotchas": [ "Owners and contacts are supplied INLINE in this payload. There are no standalone createOwner / createContact operations in the published spec (the \"add a contact\" and \"add an owner\" guides pin non-existent endpoints in their frontmatter). Use the owners[] and contacts[] arrays here instead.", "Exactly one owner must be the control prong (relationship.isControlProng: true).", "pricing.type: intent references a reusable pricing intent by pricingIntentId; the pricing intent must already exist (see manage-pricing-intents).", "The create returns HTTP 201 with a top-level processingAccountId and an initial status of \"entered\" while Payroc reviews the account. Subscribe to processingAccount.status.changed for status transitions.", "The optional reminder step (Step 2) only works when signature.type is requestedViaEmail. If you request the signature via a direct link (signature.type: requestedViaDirectLink) you cannot send reminders and Step 2 must be skipped." ], "operationIds": [ "createProcessingAccount", "createReminder" ], "workflowRefs": [], "keywords": [ "pizza", "doe", "america", "chicago", "merchantplatformid", "idempotencykey", "idempotency", "key", "doingbusinessas", "doing", "business", "businessstartdate", "start", "date", "timezone", "categorycode" ], "diagram": { "actors": [ { "id": "merchant", "name": "Merchant / business owner", "type": "human", "description": "The business whose processing account is boarded; signs the pricing agreement out of band (email or direct link). Not an API caller." }, { "id": "integrator", "name": "Integrator", "type": "client", "description": "Calls the Payroc API on the merchant's behalf to board the additional processing account." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." }, { "id": "underwriting", "name": "Payroc underwriting", "type": "external-system", "description": "Payroc's account review that runs after creation; not directly callable - observe it via the processingAccount.status.changed event." } ], "steps": [ { "title": "Create processing account", "label": "create processing account", "badge": "REST · create processing account", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "createProcessingAccount" }, { "title": "Create reminder", "label": "send signature reminder", "badge": "REST · send signature reminder", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "createReminder" }, { "title": "Sign pricing agreement", "label": "sign pricing agreement", "badge": "sign pricing agreement · not REST", "actorId": "merchant", "actorToId": "payroc-gateway" }, { "title": "Account review", "label": "notify account status", "badge": "notify account status · not REST", "actorId": "underwriting", "actorToId": "integrator" } ] } }, "adjust-a-payment": { "workflowId": "adjust-a-payment", "domain": "payments", "title": "List payments, retrieve the target payment, then adjust it", "summary": "List payments, retrieve the target payment, then adjust it", "stepCount": 3, "gotchas": [], "operationIds": [ "listPayments", "getPayment", "adjustPayment" ], "workflowRefs": [], "keywords": [ "ready", "01t15", "t15", "00z", "jane", "type", "order", "amount", "processingterminalid", "processing", "terminal", "status", "datefrom", "date", "limit", "idempotencykey" ], "diagram": { "actors": [ { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "Calls the Payroc API to find, inspect, and adjust the payment." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." } ], "steps": [ { "title": "List payments", "label": "payment search", "badge": "REST · payment search", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "listPayments" }, { "title": "Get payment", "label": "payment lookup", "badge": "REST · payment lookup", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "getPayment" }, { "title": "Adjust payment", "label": "adjustment request", "badge": "REST · adjustment request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "adjustPayment" } ] } }, "adjust-a-refund": { "workflowId": "adjust-a-refund", "domain": "payments", "title": "List, retrieve, then adjust a card refund.", "summary": "List, retrieve, then adjust a card refund.", "stepCount": 3, "gotchas": [], "operationIds": [ "listRefunds", "getRefund", "adjustRefund" ], "workflowRefs": [], "keywords": [ "orderref6543", "order", "ref6543", "ready", "01t15", "t15", "00z", "jane", "type", "status", "tostatus", "processingterminalid", "processing", "terminal", "orderid", "datefrom" ], "diagram": { "actors": [ { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "Calls the Payroc API to find, inspect, and adjust the refund." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." } ], "steps": [ { "title": "List refunds", "label": "refund search", "badge": "REST · refund search", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "listRefunds" }, { "title": "Get refund", "label": "refund lookup", "badge": "REST · refund lookup", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "getRefund" }, { "title": "Adjust refund", "label": "adjustment request", "badge": "REST · adjustment request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "adjustRefund" } ] } }, "board-a-merchant": { "workflowId": "board-a-merchant", "domain": "boarding", "title": "Create pricing, board the merchant platform, add accounts/terminals, and upload documents.", "summary": "Create pricing, board the merchant platform, add accounts/terminals, and upload documents.", "stepCount": 7, "gotchas": [ "Step 1 (create the pricing intent) is OPTIONAL. Pricing can instead be supplied inline as a pricing agreement inside the create-merchant payload (pricing.type: agreement). When you do create a pricing intent, its identifier is returned at the top-level `id` field and is passed onward as `pricingIntentId`.", "Owners and contacts are supplied INLINE in the create-merchant / create-processing-account payloads. There are NO standalone createOwner / createContact operations.", "Step 3 (add an additional processing account) is OPTIONAL - the create-merchant payload already nests the first processing account. Only run it for a business that operates more than one account.", "Step 5 (add a supporting document) is OPTIONAL and repeatable, one attachment per request.", "The MPA/signing step that returns a signed agreement (submitSignedProcessingAgreement) is x-internal and out of the public surface, so it is not a step here; the merchant signs the pricing agreement out of band (email or direct link - see create-merchant-platform)." ], "operationIds": [], "workflowRefs": [ "create-pricing-intent", "create-merchant-platform", "add-processing-account", "order-a-terminal", "add-attachment" ], "keywords": [ "9abc", "8bcd", "9cde", "8def", "unique", "identifier", "example", "corp", "privatecorporation", "private", "corporation", "pizza", "doe", "america", "chicago", "roc" ], "diagram": { "actors": [ { "id": "merchant", "name": "Merchant / business owner", "type": "human", "description": "The business being boarded. Provides its legal details, owners and contacts, and signs the pricing agreement out of band (email or direct link). Not an API caller.\n" }, { "id": "integrator", "name": "Integrator", "type": "client", "description": "Drives the boarding journey by calling the Payroc API on the merchant's behalf." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." }, { "id": "underwriting", "name": "Payroc underwriting", "type": "external-system", "description": "Payroc's account review process that approves the boarded account to process. Runs after boarding and is not directly callable; observe it via the processingAccount.status.changed event.\n" } ], "steps": [ { "title": "Pricing intent", "label": "create pricing intent", "badge": "Workflow · create pricing intent", "actorId": "integrator", "actorToId": "payroc-gateway", "workflowRef": "create-pricing-intent" }, { "title": "Merchant platform", "label": "create merchant platform", "badge": "Workflow · create merchant platform", "actorId": "integrator", "actorToId": "payroc-gateway", "workflowRef": "create-merchant-platform" }, { "title": "Sign pricing agreement", "label": "sign pricing agreement", "badge": "sign pricing agreement · not REST", "actorId": "merchant", "actorToId": "payroc-gateway" }, { "title": "Additional processing account", "label": "add processing account", "badge": "Workflow · add processing account", "actorId": "integrator", "actorToId": "payroc-gateway", "workflowRef": "add-processing-account" }, { "title": "Terminal order", "label": "order a terminal", "badge": "Workflow · order a terminal", "actorId": "integrator", "actorToId": "payroc-gateway", "workflowRef": "order-a-terminal" }, { "title": "Supporting document", "label": "upload supporting document", "badge": "Workflow · upload supporting document", "actorId": "integrator", "actorToId": "payroc-gateway", "workflowRef": "add-attachment" }, { "title": "Underwriting approval", "label": "underwriting webhook", "badge": "underwriting webhook · not REST", "actorId": "underwriting", "actorToId": "integrator" } ] } }, "cancel-a-device-payment-instruction": { "workflowId": "cancel-a-device-payment-instruction", "domain": "payroc-cloud", "title": "Confirm an instruction is in progress, then cancel it.", "summary": "Confirm an instruction is in progress, then cancel it.", "stepCount": 2, "gotchas": [], "operationIds": [ "getPaymentInstruction", "deletePaymentInstruction" ], "workflowRefs": [], "keywords": [ "paymentinstructionid", "submitpaymentinstruction", "submit", "inprogress", "getpaymentinstruction", "get", "deletepaymentinstruction", "delete", "payroc", "cloud", "http", "content", "agent", "canceling", "identifier", "returned" ], "diagram": { "actors": [ { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "The POS integration calling the Payroc API to abort the pending sale." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." }, { "id": "payment-device", "name": "Payroc Cloud payment device", "type": "external-system", "description": "Physical Payroc Cloud terminal that holds the pending instruction; not directly callable as an API step." } ], "steps": [ { "title": "Get payment instruction", "label": "instruction status check", "badge": "REST · instruction status check", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "getPaymentInstruction" }, { "title": "Cancel payment instruction", "label": "instruction cancellation", "badge": "REST · instruction cancellation", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "deletePaymentInstruction" } ] } }, "cancel-a-device-refund-instruction": { "workflowId": "cancel-a-device-refund-instruction", "domain": "payroc-cloud", "title": "Confirm an instruction is in progress, then cancel it.", "summary": "Confirm an instruction is in progress, then cancel it.", "stepCount": 2, "gotchas": [], "operationIds": [ "getRefundInstruction", "deleteRefundInstruction" ], "workflowRefs": [], "keywords": [ "refundinstructionid", "sendrefundinstruction", "send", "inprogress", "getrefundinstruction", "get", "deleterefundinstruction", "delete", "payroc", "cloud", "http", "content", "agent", "canceling", "identifier", "returned" ], "diagram": { "actors": [ { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "POS integration that calls the Payroc API to abort the pending refund." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." }, { "id": "payment-device", "name": "Payroc Cloud payment device", "type": "external-system", "description": "Physical device that holds the pending refund instruction; not directly callable as an API step." } ], "steps": [ { "title": "Get refund instruction", "label": "instruction status check", "badge": "REST · instruction status check", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "getRefundInstruction" }, { "title": "Delete refund instruction", "label": "instruction cancellation", "badge": "REST · instruction cancellation", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "deleteRefundInstruction" } ] } }, "cancel-a-device-signature-instruction": { "workflowId": "cancel-a-device-signature-instruction", "domain": "payroc-cloud", "title": "Confirm a signature instruction is still pending, then cancel it.", "summary": "Confirm a signature instruction is still pending, then cancel it.", "stepCount": 2, "gotchas": [], "operationIds": [ "getSignatureInstruction", "deleteSignatureInstruction" ], "workflowRefs": [], "keywords": [ "signatureinstructionid", "sendsignatureinstruction", "send", "inprogress", "progress", "getsignatureinstruction", "get", "deletesignatureinstruction", "delete", "payroc", "cloud", "http", "agent", "canceling", "identifier", "returned" ], "diagram": { "actors": [ { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "Calls the Payroc API to abort the pending signature capture." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." }, { "id": "payment-device", "name": "Payroc Cloud payment device", "type": "external-system", "description": "In-person Payroc Cloud device that holds the pending instruction; not directly callable as an API step." } ], "steps": [ { "title": "Get signature instruction", "label": "instruction status check", "badge": "REST · instruction status check", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "getSignatureInstruction" }, { "title": "Cancel signature instruction", "label": "instruction cancellation", "badge": "REST · instruction cancellation", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "deleteSignatureInstruction" } ] } }, "capture-signature-on-a-device": { "workflowId": "capture-signature-on-a-device", "domain": "payroc-cloud", "title": "Submit a signature instruction to a device, then retrieve the captured signature.", "summary": "Submit a signature instruction to a device, then retrieve the captured signature.", "stepCount": 3, "gotchas": [], "operationIds": [ "sendSignatureInstruction", "getSignatureInstruction", "retrieveSignature" ], "workflowRefs": [], "keywords": [ "jdn4ilzb0t", "jdn4", "ilzb0", "serialnumber", "serial", "number", "processingterminalid", "processing", "terminal", "idempotencykey", "idempotency", "key", "signatureid", "path", "body", "uuid" ], "diagram": { "actors": [ { "id": "cardholder", "name": "Cardholder", "type": "human", "description": "Person at the point of sale who signs on the payment device." }, { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "Calls the Payroc API to prompt for and retrieve the signature." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." }, { "id": "payment-device", "name": "Payroc Cloud payment device", "type": "external-system", "description": "In-person Payroc Cloud device that displays the prompt and captures the signature; driven via instructions, not directly callable." } ], "steps": [ { "title": "Submit signature instruction", "label": "signature instruction", "badge": "REST · signature instruction", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "sendSignatureInstruction" }, { "title": "Get signature instruction", "label": "instruction status poll", "badge": "REST · instruction status poll", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "getSignatureInstruction" }, { "title": "Retrieve signature", "label": "signature retrieval", "badge": "REST · signature retrieval", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "retrieveSignature" } ] } }, "check-dcc-eligibility": { "workflowId": "check-dcc-eligibility", "domain": "payments", "title": "Verify DCC eligibility and retrieve a currency conversion quote for a card.", "summary": "Verify DCC eligibility and retrieve a currency conversion quote for a card.", "stepCount": 1, "gotchas": [], "operationIds": [ "getFxRates" ], "workflowRefs": [], "keywords": [ "web", "pos", "moto", "jane", "usd", "sarah", "hazel", "hopper", "processingterminalid", "processing", "terminal", "channel", "operator", "baseamount", "base", "amount" ], "diagram": { "actors": [ { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "Calls the Payroc API to check whether the customer's card is eligible for DCC and obtain a rate quote." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." } ], "steps": [ { "title": "Get FX rates", "label": "DCC rate inquiry", "badge": "REST · DCC rate inquiry", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "getFxRates" } ] } }, "check-ebt-balance": { "workflowId": "check-ebt-balance", "domain": "payments", "title": "Submit an EBT balance inquiry and return the card's benefit balance.", "summary": "Submit an EBT balance inquiry and return the card's benefit balance.", "stepCount": 1, "gotchas": [], "operationIds": [ "balanceCard" ], "workflowRefs": [], "keywords": [ "jane", "usd", "sarah", "hazel", "hopper", "cash", "processingterminalid", "processing", "terminal", "operator", "currency", "cardholdername", "cardholder", "name", "cardnumber", "number" ], "diagram": { "actors": [ { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "Submits the EBT balance inquiry to the Payroc API." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." }, { "id": "processor", "name": "EBT processor", "type": "external-system", "description": "Downstream processor that approves or declines the balance inquiry; not directly callable." } ], "steps": [ { "title": "Balance inquiry", "label": "balance inquiry", "badge": "REST · balance inquiry", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "balanceCard" } ] } }, "close-a-terminal-batch": { "workflowId": "close-a-terminal-batch", "domain": "payments", "title": "Close the current batch for a processing terminal.", "summary": "Close the current batch for a processing terminal.", "stepCount": 1, "gotchas": [ "the request carries no body; the Idempotency-Key header is REQUIRED (a missing key is a 400, not a 409); the batch is identified only by the terminal, so there is no batchId input. After the gateway closes the batch, the merchant can view its details in the Self-Care Portal." ], "operationIds": [ "closeBatch" ], "workflowRefs": [], "keywords": [ "processingterminalid", "idempotencykey", "idempotency", "key", "uuid", "closebatch", "http", "cutofftime", "cut", "off", "time", "post", "required", "batchid", "self", "care" ], "diagram": { "actors": [ { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "Calls the Payroc API to close the terminal's open batch." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." } ], "steps": [ { "title": "Close batch", "label": "close batch request", "badge": "REST · close batch request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "closeBatch" } ] } }, "close-ach-return": { "workflowId": "close-ach-return", "domain": "payments", "title": "Retrieve a returned ACH payment, then close the return.", "summary": "Retrieve a returned ACH payment, then close the return.", "stepCount": 2, "gotchas": [], "operationIds": [ "getBankTransferPayment", "closeBankTransferPayment" ], "workflowRefs": [], "keywords": [ "m2mjog6o2y", "mjog6", "paymentid", "idempotencykey", "idempotency", "key", "uuid", "returnpaymentid", "nacha", "own", "getbanktransferpayment", "get", "bank", "transfer", "closebanktransferpayment", "post" ], "diagram": { "actors": [ { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "Calls the Payroc API to retrieve the returned payment and close the return." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." }, { "id": "ach-network", "name": "ACH network", "type": "external-system", "description": "Returned the original bank-transfer payment; not directly callable - closing the return is the alternative to re-presenting to it." } ], "steps": [ { "title": "Retrieve payment", "label": "payment lookup", "badge": "REST · payment lookup", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "getBankTransferPayment" }, { "title": "Close return", "label": "close return request", "badge": "REST · close return request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "closeBankTransferPayment" } ] } }, "collect-with-hosted-fields": { "workflowId": "collect-with-hosted-fields", "domain": "payments", "title": "Create a Hosted Fields session, tokenize card details client-side, then run the sale.", "summary": "Create a Hosted Fields session, tokenize card details client-side, then run the sale.", "stepCount": 3, "gotchas": [], "operationIds": [ "createSession", "payment" ], "workflowRefs": [], "keywords": [ "4d5e", "4f6a", "8b9c", "orderref6543", "order", "ref6543", "large", "pepperoni", "pizza", "usd", "jane", "processingterminalid", "processing", "terminal", "sessionidempotencykey", "idempotency" ], "diagram": { "actors": [ { "id": "customer", "name": "Customer", "type": "human", "description": "Cardholder / account holder who enters their payment details into the Hosted Fields form." }, { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "Hosts the checkout page and calls the Payroc API server-side to create the session and run the payment." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call; also hosts the embedded fields and issues the single-use token." }, { "id": "processor", "name": "Payment processor", "type": "external-system", "description": "Downstream processor / card scheme / ACH network that authorizes the funds; not directly callable." } ], "steps": [ { "title": "Create hosted fields session", "label": "session request", "badge": "REST · session request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "createSession" }, { "title": "Customer submits payment details", "label": "hosted fields submit", "badge": "hosted fields submit · not REST", "actorId": "customer", "actorToId": "payroc-gateway" }, { "title": "Run sale with token", "label": "sale request", "badge": "REST · sale request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "payment" } ] } }, "collect-with-hosted-payment-page": { "workflowId": "collect-with-hosted-payment-page", "domain": "payments", "title": "Collect a payment via Payroc's redirect-based Hosted Payment Page, optionally capturing a pre-authorization afterward.", "summary": "Collect a payment via Payroc's redirect-based Hosted Payment Page, optionally capturing a pre-authorization afterward.", "stepCount": 4, "gotchas": [ "The capture step applies ONLY to the pre-authorization variant. For a plain sale, do not call capturePayment - the redirect/webhook already settled it.", "You need the paymentId to capture. The gateway returns it to the merchant's return URL and via webhook after the customer completes the HPP; it is not obtained from a REST call in this workflow.", "Sending an amount captures that value; omit amount to capture the full authorized amount. Capturing more than authorized requires adjusting the pre-authorization first (see run-a-pre-authorization).", "Every REST request requires a unique Idempotency-Key header (UUID v4). Reusing a key replays the original response." ], "operationIds": [ "capturePayment" ], "workflowRefs": [], "keywords": [ "m2mjog6o2y", "mjog6", "jane", "idempotencykey", "idempotency", "key", "paymentid", "processingterminalid", "processing", "terminal", "operator", "captureamount", "capture", "amount", "uuid", "url" ], "diagram": { "actors": [ { "id": "customer", "name": "Customer", "type": "human", "description": "Cardholder who is redirected to the Hosted Payment Page and submits their payment details." }, { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "Runs the website that loads the Hosted Payment Page and calls the Payroc API to capture a pre-authorization." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "Hosts the payment page, processes the transaction, and exposes the REST surface these steps call." }, { "id": "processor", "name": "Payment processor", "type": "external-system", "description": "Downstream card/bank processor and issuing bank that authorize and settle the funds; not directly callable." } ], "steps": [ { "title": "Load hosted payment page", "label": "signed form POST", "badge": "signed form POST · not REST", "actorId": "merchant", "actorToId": "payroc-gateway" }, { "title": "Customer submits payment details", "label": "hosted page submit", "badge": "hosted page submit · not REST", "actorId": "customer", "actorToId": "payroc-gateway" }, { "title": "Receive payment result", "label": "payment result webhook", "badge": "payment result webhook · not REST", "actorId": "payroc-gateway", "actorToId": "merchant" }, { "title": "Capture hosted pre authorization", "label": "capture request", "badge": "REST · capture request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "capturePayment" } ] } }, "collect-with-payment-link": { "workflowId": "collect-with-payment-link", "domain": "payments", "title": "Create a payment link, share it by email, track sharing events, and manage its lifecycle.", "summary": "Create a payment link, share it by email, track sharing events, and manage its lifecycle.", "stepCount": 8, "gotchas": [ "The create body is polymorphic on `type`: `multiUse` (a reusable link the merchant can take multiple payments with) vs `singleUse` (a one-off link for a single payment). This workflow models the reusable `multiUse` variant as the primary path; the one-off variant is identical in shape but sends `type: singleUse`, requires an `order.orderId` and `expiresOn`, and the link moves to `completed` after the single payment. Collapse both into this one family - do not split files.", "Inside `order.charge` the amount ownership is also polymorphic on `type`: `prompt` (the customer enters the amount - send only `currency`) vs `preset` (the merchant sets the amount - send `amount` and `currency`). The primary path uses `prompt`.", "`createPaymentLink` and `listPaymentLinks` are keyed by the `processingTerminalId` (path). Every follow-on action (share, retrieve, update, deactivate, list sharing events) is keyed by the `paymentLinkId` that create returns.", "`updatePaymentLink` is an RFC 6902 JSON Patch (`PATCH`) - the body is an array of patch operations (e.g. replace `/expiresOn`), NOT a full resource. Updating a single-use link regenerates its payment URL, so the original link stops working.", "Write requests (create, share, update) require a unique `Idempotency-Key` header (UUID v4). Use a fresh key per request; reusing a key replays the original response. `deactivatePaymentLink` and the read/list steps take no idempotency key.", "Deactivation is terminal: once deactivated the link cannot be used or reactivated." ], "operationIds": [ "createPaymentLink", "sharePaymentLink", "listPaymentLinkShareEvents", "retrievePaymentLink", "updatePaymentLink", "listPaymentLinks", "deactivatePaymentLink" ], "workflowRefs": [], "keywords": [ "9abc", "8bcd", "linkref6543", "ref6543", "pie", "forward", "charitable", "trust", "donation", "usd", "sarah", "hazel", "hopper", "example", "com", "dear" ], "diagram": { "actors": [ { "id": "customer", "name": "Customer", "type": "human", "description": "Recipient who receives the payment link by email and pays through the hosted page." }, { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "Calls the Payroc API to create, share, and manage the payment link on the customer's behalf." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call; also hosts the payment page and emails the link." }, { "id": "processor", "name": "Payment processor", "type": "external-system", "description": "Downstream processor that settles the payment when the customer pays through the link; not directly callable." } ], "steps": [ { "title": "Create payment link", "label": "create link request", "badge": "REST · create link request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "createPaymentLink" }, { "title": "Share payment link", "label": "share link request", "badge": "REST · share link request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "sharePaymentLink" }, { "title": "List sharing events", "label": "sharing events lookup", "badge": "REST · sharing events lookup", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "listPaymentLinkShareEvents" }, { "title": "Customer pays through link", "label": "hosted link payment", "badge": "hosted link payment · not REST", "actorId": "customer", "actorToId": "payroc-gateway" }, { "title": "Retrieve payment link", "label": "link lookup", "badge": "REST · link lookup", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "retrievePaymentLink" }, { "title": "Update payment link", "label": "JSON Patch update", "badge": "REST · JSON Patch update", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "updatePaymentLink" }, { "title": "List payment links", "label": "list links request", "badge": "REST · list links request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "listPaymentLinks" }, { "title": "Deactivate payment link", "label": "deactivate request", "badge": "REST · deactivate request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "deactivatePaymentLink" } ] } }, "configure-a-device": { "workflowId": "configure-a-device", "domain": "payroc-cloud", "title": "Retrieve terminal, host, and device configuration for a Payroc Cloud device.", "summary": "Retrieve terminal, host, and device configuration for a Payroc Cloud device.", "stepCount": 3, "gotchas": [], "operationIds": [ "getProcessingTerminal", "getProcessingTerminalHostConfiguration", "retrieveDeviceConfiguration" ], "workflowRefs": [], "keywords": [ "idtechkioskv", "idtech", "kiosk", "processingterminalid", "processing", "model", "tech", "paxa920pro", "pax", "a920", "pro", "android", "ingenicoaxiumrx7000", "ingenico", "axium", "rx7000" ], "diagram": { "actors": [ { "id": "integrator", "name": "Integrator", "type": "client", "description": "Runs the read-only configuration lookups; the only API caller in this workflow." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." } ], "steps": [ { "title": "Get processing terminal", "label": "processing terminal lookup", "badge": "REST · processing terminal lookup", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "getProcessingTerminal" }, { "title": "Get processing terminal host configuration", "label": "host configuration lookup", "badge": "REST · host configuration lookup", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "getProcessingTerminalHostConfiguration" }, { "title": "Retrieve device configuration", "label": "device configuration lookup", "badge": "REST · device configuration lookup", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "retrieveDeviceConfiguration" } ] } }, "create-event-subscription": { "workflowId": "create-event-subscription", "domain": "notifications", "title": "Create an event subscription, then discover, retrieve, and delete it.", "summary": "Create an event subscription, then discover, retrieve, and delete it.", "stepCount": 5, "gotchas": [ "The response id field is the subscriptionId. The create/list/get responses return it at `#/id` (an int64), and every follow-on step ({subscriptionId} path parameter) takes that value. Do not confuse it with the eventTypes or notification objects.", "The secret you send is masked in every response (last 6 characters shown, first 10 masked, e.g. `**********oP3456`), so you cannot read it back — keep your own copy.", "To amend a subscription, use the update-an-event-subscription (PUT full replace) or patch-an-event-subscription (PATCH partial) workflow — those are two mutually-exclusive update paths.", "Idempotency-Key (UUID v4) is a required header on the create operation.", "The webhook receiver itself (return a 200 to each delivery, verify the Payroc-Secret header, handle the CloudEvents payload) is caller-side and is not a Payroc API operation, so it is not a step here." ], "operationIds": [ "createEventSubscription", "listEventSubscriptions", "getEventSubscription", "deleteEventSubscription" ], "workflowRefs": [], "keywords": [ "processingaccount", "processing", "account", "status", "changed", "https", "server", "notification", "endpoint", "abcd1234efgh5678ijkl9012mnop3456", "d1234e", "h5678i", "l9012m", "p3456", "jane", "doe" ], "diagram": { "actors": [ { "id": "integrator", "name": "Integrator", "type": "client", "description": "Registers and manages the subscription, and hosts the webhook endpoint that receives event deliveries." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call; delivers event notifications to the subscribed endpoint." } ], "steps": [ { "title": "Create subscription", "label": "create event subscription", "badge": "REST · create event subscription", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "createEventSubscription" }, { "title": "Deliver event notification", "label": "deliver event notification", "badge": "deliver event notification · not REST", "actorId": "payroc-gateway", "actorToId": "integrator" }, { "title": "List subscriptions", "label": "list event subscriptions", "badge": "REST · list event subscriptions", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "listEventSubscriptions" }, { "title": "Get subscription", "label": "get event subscription", "badge": "REST · get event subscription", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "getEventSubscription" }, { "title": "Delete subscription", "label": "delete event subscription", "badge": "REST · delete event subscription", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "deleteEventSubscription" } ] } }, "create-merchant-platform": { "workflowId": "create-merchant-platform", "domain": "boarding", "title": "Create a merchant platform, then optionally remind the merchant to sign.", "summary": "Create a merchant platform, then optionally remind the merchant to sign.", "stepCount": 3, "gotchas": [ "owners carry a relationship with isControlProng (you must nominate one control prong) and equityPercentage; the pricing block references a reusable pricingIntentId rather than inline pricing; and the optional reminder step only works when the processing account requested the merchant's signature by email (signature.type = requestedViaEmail) — it fails for a direct-link signature." ], "operationIds": [ "createMerchant", "createReminder" ], "workflowRefs": [], "keywords": [ "example", "corp", "privatecorporation", "private", "corporation", "pizza", "doe", "pricingagreement", "pricing", "agreement", "idempotencykey", "idempotency", "key", "businessname", "business", "name" ], "diagram": { "actors": [ { "id": "merchant", "name": "Merchant / business owner", "type": "human", "description": "The business being boarded; signs the pricing agreement out of band (email or direct link). Not an API caller." }, { "id": "integrator", "name": "Integrator", "type": "client", "description": "Calls the Payroc API on the merchant's behalf to board the business." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." } ], "steps": [ { "title": "Create merchant", "label": "create merchant platform", "badge": "REST · create merchant platform", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "createMerchant" }, { "title": "Create reminder", "label": "send signature reminder", "badge": "REST · send signature reminder", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "createReminder" }, { "title": "Sign pricing agreement", "label": "sign pricing agreement", "badge": "sign pricing agreement · not REST", "actorId": "merchant", "actorToId": "payroc-gateway" } ] } }, "create-pricing-intent": { "workflowId": "create-pricing-intent", "domain": "boarding", "title": "Create a reusable pricing intent (fee template) for processing accounts.", "summary": "Create a reusable pricing intent (fee template) for processing accounts.", "stepCount": 1, "gotchas": [ "base fees are always required; processor fees carry the pricing program (planType, e.g. interchangePlus / interchangePlusPlus / tiered) and per-transaction fees; gateway fees are optional. The create request is idempotent and requires an Idempotency-Key header (UUID v4). On success the gateway returns the new pricing intent with status pendingReview and its identifier at the top-level `id` field (not `pricingIntentId`) - that value is what later boarding calls pass as pricingIntentId to assign the template to a processing account." ], "operationIds": [ "createPricingIntent" ], "workflowRefs": [], "keywords": [ "unique", "identifier", "idempotencykey", "idempotency", "key", "country", "version", "uuid", "iso", "agreement", "mpa", "post", "interchangeplus", "interchange", "plus", "ach" ], "diagram": { "actors": [ { "id": "integrator", "name": "Integrator", "type": "client", "description": "Creates the reusable fee template; the only API caller in this workflow." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." } ], "steps": [ { "title": "Create pricing intent", "label": "create pricing intent", "badge": "REST · create pricing intent", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "createPricingIntent" } ] } }, "deactivate-a-subscription": { "workflowId": "deactivate-a-subscription", "domain": "payments", "title": "Deactivate a subscription to stop collection.", "summary": "Deactivate a subscription to stop collection.", "stepCount": 1, "gotchas": [ "`subscriptionId` is the merchant-assigned string (for example `SubRef7654`) used on create, not a gateway-generated id.", "`deactivateSubscription` requires no request body and no Idempotency-Key header." ], "operationIds": [ "deactivateSubscription" ], "workflowRefs": [], "keywords": [ "subref7654", "sub", "ref7654", "processingterminalid", "processing", "terminal", "subscriptionid", "deactivatesubscription", "post", "idempotency", "key", "returns", "agent", "unique", "identifier", "owns" ], "diagram": { "actors": [ { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "Calls the Payroc API to stop collection for the subscription." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." } ], "steps": [ { "title": "Deactivate subscription", "label": "deactivate request", "badge": "REST · deactivate request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "deactivateSubscription" } ] } }, "delete-a-contact": { "workflowId": "delete-a-contact", "domain": "boarding", "title": "List, retrieve, then delete a processing account's contact.", "summary": "List, retrieve, then delete a processing account's contact.", "stepCount": 3, "gotchas": [ "contactId is an integer (e.g. 1543), not a string; it is issued by the gateway when the processing account is created and is also discoverable via the list step.", "You cannot delete the last contact on a processing account — the API requires at least one contact to remain and rejects the deletion.", "deleteContact returns 204 No Content and is destructive and irreversible; run only when the contact should be removed." ], "operationIds": [ "listProcessingAccountContacts", "getContact", "deleteContact" ], "workflowRefs": [], "keywords": [ "processingaccountid", "contactid", "limit", "listcontacts", "contacts", "getcontact", "get", "deletecontact", "api", "content", "agent", "unique", "identifier", "gateway", "assigned", "integer" ], "diagram": { "actors": [ { "id": "integrator", "name": "Integrator", "type": "client", "description": "Finds and deletes the contact; the only API caller in this workflow." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." } ], "steps": [ { "title": "List contacts", "label": "list contacts", "badge": "REST · list contacts", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "listProcessingAccountContacts" }, { "title": "Get contact", "label": "get contact", "badge": "REST · get contact", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "getContact" }, { "title": "Delete contact", "label": "delete contact", "badge": "REST · delete contact", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "deleteContact" } ] } }, "delete-a-funding-account": { "workflowId": "delete-a-funding-account", "domain": "funding", "title": "List, retrieve, then delete a funding account.", "summary": "List, retrieve, then delete a funding account.", "stepCount": 3, "gotchas": [ "A funding account's fundingAccountId is an integer, not one of the alphanumeric ids used elsewhere in the API.", "Delete only applies to a funding account associated with a FUNDING RECIPIENT. You cannot delete a funding account associated with a processing account - the API rejects those.", "You cannot delete the last funding account on a funding recipient — the API requires at least one funding account to remain and rejects the deletion.", "`deleteFundingAccount` returns 204 No Content, so there is no response body to capture." ], "operationIds": [ "listFundingAccount", "getFundingAccount", "deleteFundingAccount" ], "workflowRefs": [], "keywords": [ "fundingaccountid", "limit", "listfundingaccounts", "accounts", "getfundingaccount", "get", "deletefundingaccount", "ach", "payroc", "api", "recipient", "content", "discover", "agent", "mutually", "unique" ], "diagram": { "actors": [ { "id": "integrator", "name": "Integrator", "type": "client", "description": "Finds and deletes the funding account; the only API caller in this workflow." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." } ], "steps": [ { "title": "List funding accounts", "label": "list funding accounts", "badge": "REST · list funding accounts", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "listFundingAccount" }, { "title": "Get funding account", "label": "get funding account", "badge": "REST · get funding account", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "getFundingAccount" }, { "title": "Delete funding account", "label": "delete funding account", "badge": "REST · delete funding account", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "deleteFundingAccount" } ] } }, "delete-a-funding-instruction": { "workflowId": "delete-a-funding-instruction", "domain": "funding", "title": "List, retrieve, then delete a funding instruction.", "summary": "List, retrieve, then delete a funding instruction.", "stepCount": 3, "gotchas": [], "operationIds": [ "listInstructions", "getInstruction", "deleteInstructions" ], "workflowRefs": [], "keywords": [ "datefrom", "date", "dateto", "after", "limit", "instructionid", "yyyy", "listinstructions", "instructions", "getinstruction", "get", "deleteinstructions", "payroc", "ach", "create", "operationid" ], "diagram": { "actors": [ { "id": "integrator", "name": "Integrator", "type": "client", "description": "Finds and deletes the funding instruction; the only API caller in this workflow." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." } ], "steps": [ { "title": "List instructions", "label": "list funding instructions", "badge": "REST · list funding instructions", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "listInstructions" }, { "title": "Get instruction", "label": "get funding instruction", "badge": "REST · get funding instruction", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "getInstruction" }, { "title": "Delete instruction", "label": "delete funding instruction", "badge": "REST · delete funding instruction", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "deleteInstructions" } ] } }, "delete-a-funding-recipient": { "workflowId": "delete-a-funding-recipient", "domain": "funding", "title": "List, retrieve, then delete a funding recipient.", "summary": "List, retrieve, then delete a funding recipient.", "stepCount": 3, "gotchas": [ "The path parameter is recipientId (an integer).", "deleteFundingRecipient is destructive and CASCADES: it removes the recipient together with all of its funding accounts and owners. Returns 204 No Content." ], "operationIds": [ "listFundingRecipients", "getFundingRecipient", "deleteFundingRecipient" ], "workflowRefs": [], "keywords": [ "recipientid", "limit", "listrecipients", "recipients", "getrecipient", "get", "deleterecipient", "deletefundingrecipient", "cascades", "content", "discover", "agent", "returns", "mutually", "unique", "identifier" ], "diagram": { "actors": [ { "id": "integrator", "name": "Integrator", "type": "client", "description": "Finds and deletes the funding recipient; the only API caller in this workflow." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." } ], "steps": [ { "title": "List recipients", "label": "list funding recipients", "badge": "REST · list funding recipients", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "listFundingRecipients" }, { "title": "Get recipient", "label": "get funding recipient", "badge": "REST · get funding recipient", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "getFundingRecipient" }, { "title": "Delete recipient", "label": "delete funding recipient", "badge": "REST · delete funding recipient", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "deleteFundingRecipient" } ] } }, "delete-a-payment-plan": { "workflowId": "delete-a-payment-plan", "domain": "payments", "title": "List, retrieve, then delete a payment plan.", "summary": "List, retrieve, then delete a payment plan.", "stepCount": 3, "gotchas": [ "`paymentPlanId` is merchant-assigned and is the `{paymentPlanId}` path parameter.", "`deletePaymentPlan` is a DELETE that returns 204 (no body). It is irreversible — the plan cannot be recovered and no further subscriptions can be added to it. The plan's `onDelete` value (`complete` vs `continue`) determines whether existing subscriptions stop or keep running." ], "operationIds": [ "listPaymentPlans", "getPaymentPlan", "deletePaymentPlan" ], "workflowRefs": [], "keywords": [ "planref8765", "ref8765", "processingterminalid", "processing", "terminal", "paymentplanid", "limit", "listpaymentplans", "plans", "getpaymentplan", "get", "deletepaymentplan", "ondelete", "discover", "agent", "mutually" ], "diagram": { "actors": [ { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "Calls the Payroc API to find and delete the payment plan." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." } ], "steps": [ { "title": "List payment plans", "label": "plan search", "badge": "REST · plan search", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "listPaymentPlans" }, { "title": "Get payment plan", "label": "plan lookup", "badge": "REST · plan lookup", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "getPaymentPlan" }, { "title": "Delete payment plan", "label": "delete plan request", "badge": "REST · delete plan request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "deletePaymentPlan" } ] } }, "delete-a-saved-payment-method": { "workflowId": "delete-a-saved-payment-method", "domain": "payments", "title": "List, retrieve, then delete a secure token.", "summary": "List, retrieve, then delete a secure token.", "stepCount": 3, "gotchas": [ "The path parameter is the `secureTokenId` (format `MREF_...`), the durable handle for the stored payment method.", "`deleteSecureToken` is a DELETE that returns 204 (no body). It is irreversible — the token and its `secureTokenId` cannot be recovered or reused." ], "operationIds": [ "listSecureTokens", "getSecureToken", "deleteSecureToken" ], "workflowRefs": [], "keywords": [ "mref", "sarah", "20hazel", "hazel", "20hopper", "hopper", "processingterminalid", "processing", "terminal", "securetokenid", "customername", "customer", "name", "limit", "url", "listsecuretokens" ], "diagram": { "actors": [ { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "Calls the Payroc API to find and delete the stored secure token." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." } ], "steps": [ { "title": "List secure tokens", "label": "token search", "badge": "REST · token search", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "listSecureTokens" }, { "title": "Get secure token", "label": "token lookup", "badge": "REST · token lookup", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "getSecureToken" }, { "title": "Delete secure token", "label": "delete token request", "badge": "REST · delete token request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "deleteSecureToken" } ] } }, "delete-an-owner": { "workflowId": "delete-an-owner", "domain": "boarding", "title": "List, retrieve, then delete an owner of a funding recipient.", "summary": "List, retrieve, then delete an owner of a funding recipient.", "stepCount": 3, "gotchas": [], "operationIds": [ "listFundRecipientOwners", "getOwner", "deleteOwner" ], "workflowRefs": [], "keywords": [ "4ab5c", "recipientid", "ownerid", "create", "owners", "listfundrecipientowners", "fund", "getowner", "get", "deleteowner", "api", "processingaccountid", "processing", "account", "content", "returned" ], "diagram": { "actors": [ { "id": "integrator", "name": "Integrator", "type": "client", "description": "Finds and deletes the owner; the only API caller in this workflow." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." } ], "steps": [ { "title": "List owners", "label": "list owners", "badge": "REST · list owners", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "listFundRecipientOwners" }, { "title": "Get owner", "label": "get owner", "badge": "REST · get owner", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "getOwner" }, { "title": "Delete owner", "label": "delete owner", "badge": "REST · delete owner", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "deleteOwner" } ] } }, "look-up-bin": { "workflowId": "look-up-bin", "domain": "payments", "title": "Look up card details from a BIN.", "summary": "Look up card details from a BIN.", "stepCount": 1, "gotchas": [], "operationIds": [ "binLookup" ], "workflowRefs": [], "keywords": [ "usd", "processingterminalid", "processing", "terminal", "amount", "currency", "iso", "binlookup", "lookup", "fsa", "hsa", "cardbin", "securetoken", "secure", "token", "digitalwallet" ], "diagram": { "actors": [ { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "Calls the Payroc API to look up card details from a BIN before taking a payment." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." } ], "steps": [ { "title": "Look up BIN", "label": "BIN lookup", "badge": "REST · BIN lookup", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "binLookup" } ] } }, "manage-funding-recipients": { "workflowId": "manage-funding-recipients", "domain": "funding", "title": "Discover a funding recipient, retrieve it, and read its nested accounts and owners.", "summary": "Discover a funding recipient, retrieve it, and read its nested accounts and owners.", "stepCount": 4, "gotchas": [ "The path parameter is recipientId (an integer), returned as recipientId in create/list/get responses. It is NOT the fundingAccountId or ownerId of the nested resources.", "Contacts and owners are supplied inline in the recipient payload - there is no standalone createContact/createOwner operation." ], "operationIds": [ "listFundingRecipients", "getFundingRecipient", "listFundRecipientFundingAccounts", "listFundRecipientOwners" ], "workflowRefs": [], "keywords": [ "recipientid", "limit", "listrecipients", "list", "fundingaccountid", "account", "ownerid", "owner", "createcontact", "create", "contact", "createowner", "optional", "agent", "contacts", "unique" ], "diagram": { "actors": [ { "id": "integrator", "name": "Integrator", "type": "client", "description": "Reads the funding recipient and its nested resources; the only API caller in this workflow." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." } ], "steps": [ { "title": "List recipients", "label": "list funding recipients", "badge": "REST · list funding recipients", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "listFundingRecipients" }, { "title": "Get recipient", "label": "get funding recipient", "badge": "REST · get funding recipient", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "getFundingRecipient" }, { "title": "List recipient funding accounts", "label": "list funding accounts", "badge": "REST · list funding accounts", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "listFundRecipientFundingAccounts" }, { "title": "List recipient owners", "label": "list owners", "badge": "REST · list owners", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "listFundRecipientOwners" } ] } }, "manage-payment-plans": { "workflowId": "manage-payment-plans", "domain": "payments", "title": "Create, list, and retrieve a payment plan", "summary": "Create, list, and retrieve a payment plan", "stepCount": 3, "gotchas": [], "operationIds": [ "createPaymentPlan", "listPaymentPlans", "getPaymentPlan" ], "workflowRefs": [], "keywords": [ "planref8765", "ref8765", "premium", "club", "usd", "monthly", "processingterminalid", "processing", "terminal", "paymentplanid", "idempotencykey", "idempotency", "key", "name", "currency", "frequency" ], "diagram": { "actors": [ { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "Calls the Payroc API to create, list, and retrieve the payment plan." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." } ], "steps": [ { "title": "Create payment plan", "label": "create plan request", "badge": "REST · create plan request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "createPaymentPlan" }, { "title": "List payment plans", "label": "plan search", "badge": "REST · plan search", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "listPaymentPlans" }, { "title": "Get payment plan", "label": "plan lookup", "badge": "REST · plan lookup", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "getPaymentPlan" } ] } }, "manage-pricing-intents": { "workflowId": "manage-pricing-intents", "domain": "boarding", "title": "Create, list, retrieve, and delete a pricing intent.", "summary": "Create, list, retrieve, and delete a pricing intent.", "stepCount": 4, "gotchas": [ "Create requires a unique `Idempotency-Key` header (UUID v4); replaying the same key returns the original result rather than creating a duplicate.", "A newly created pricing intent is returned with `status: pendingReview` - Payroc must approve it (status becomes `active`) before it is usable in boarding. Approval is out-of-band and is not a step here.", "The write payload is MPA version 5.2 (`writePricingIntent`); `country`, `version`, `base`, and `key` are required. Fee amounts are integers in the currency's lowest denomination (cents).", "Deletion is irreversible - a deleted pricing intent cannot be recovered or assigned to a boarding application.", "Deleting a pricing intent does not affect merchants that are already boarded - the pricing data was applied to their processing account at boarding time." ], "operationIds": [ "createPricingIntent", "listPricingIntents", "getPricingIntent", "deletePricingIntent" ], "workflowRefs": [], "keywords": [ "unique", "identifier", "idempotencykey", "idempotency", "key", "pricingintentid", "limit", "uuid", "payroc", "merchant", "platform", "processing", "account", "pendingreview", "pending", "review" ], "diagram": { "actors": [ { "id": "integrator", "name": "Integrator", "type": "client", "description": "Manages the pricing-intent lifecycle; the only API caller in this workflow." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." } ], "steps": [ { "title": "Create pricing intent", "label": "create pricing intent", "badge": "REST · create pricing intent", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "createPricingIntent" }, { "title": "List pricing intents", "label": "list pricing intents", "badge": "REST · list pricing intents", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "listPricingIntents" }, { "title": "Get pricing intent", "label": "get pricing intent", "badge": "REST · get pricing intent", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "getPricingIntent" }, { "title": "Delete pricing intent", "label": "delete pricing intent", "badge": "REST · delete pricing intent", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "deletePricingIntent" } ] } }, "manage-subscriptions": { "workflowId": "manage-subscriptions", "domain": "payments", "title": "Create, list, retrieve, update, and manually pay a subscription", "summary": "Create, list, retrieve, update, and manually pay a subscription", "stepCount": 5, "gotchas": [], "operationIds": [ "createSubscription", "listSubscriptions", "getSubscription", "updateSubscription", "paySubscription" ], "workflowRefs": [], "keywords": [ "subref7654", "sub", "ref7654", "planref8765", "plan", "ref8765", "9abc", "8bcd", "sarah", "20hazel", "hazel", "20hopper", "hopper", "replace", "path", "recurringorder" ], "diagram": { "actors": [ { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "Calls the Payroc API to create, find, inspect, update, and manually pay the subscription." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." } ], "steps": [ { "title": "Create subscription", "label": "create subscription request", "badge": "REST · create subscription request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "createSubscription" }, { "title": "List subscriptions", "label": "subscription search", "badge": "REST · subscription search", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "listSubscriptions" }, { "title": "Get subscription", "label": "subscription lookup", "badge": "REST · subscription lookup", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "getSubscription" }, { "title": "Update subscription", "label": "JSON Patch update", "badge": "REST · JSON Patch update", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "updateSubscription" }, { "title": "Pay subscription", "label": "manual payment request", "badge": "REST · manual payment request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "paySubscription" } ] } }, "order-a-terminal": { "workflowId": "order-a-terminal", "domain": "boarding", "title": "Create a terminal order for a processing account and track its status.", "summary": "Create a terminal order for a processing account and track its status.", "stepCount": 2, "gotchas": [ "createTerminalOrder requires an Idempotency-Key header (UUID v4). The order does not become a terminal instantly - the response status is typically `open` and moves through held/dispatched/fulfilled/cancelled asynchronously, so callers should either poll getTerminalOrder (step 2) or subscribe to the terminalOrder.status.changed event rather than expect a provisioned terminal from step 1. This is a single-actor workflow driven by the integrator." ], "operationIds": [ "createTerminalOrder", "getTerminalOrder" ], "workflowRefs": [], "keywords": [ "roc", "services", "dx8000", "processingaccountid", "idempotencykey", "idempotency", "key", "solutiontemplateid", "solution", "template", "uuid", "createterminalorder", "terminalorderid", "getterminalorder", "get", "terminalorder" ], "diagram": { "actors": [ { "id": "integrator", "name": "Integrator", "type": "client", "description": "Places and tracks the terminal order; the only API caller in this workflow." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." } ], "steps": [ { "title": "Create terminal order", "label": "place terminal order", "badge": "REST · place terminal order", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "createTerminalOrder" }, { "title": "Get terminal order", "label": "track order status", "badge": "REST · track order status", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "getTerminalOrder" } ] } }, "patch-a-pricing-intent": { "workflowId": "patch-a-pricing-intent", "domain": "boarding", "title": "Partially update a pricing intent via PATCH.", "summary": "Partially update a pricing intent via PATCH.", "stepCount": 1, "gotchas": [ "Partially update requires a unique `Idempotency-Key` header (UUID v4); replaying the same key returns the original result rather than applying the patch twice.", "The body is an RFC 6902 JSON Patch document (an array of `op`/`path`/`value` operations), NOT a plain resource object. PATCH returns 200 with the updated pricing intent body.", "Updating a pricing intent never affects merchants you have already onboarded; it only changes the template for future assignments." ], "operationIds": [ "patchPricingIntent" ], "workflowRefs": [], "keywords": [ "idempotencykey", "idempotency", "key", "pricingintentid", "uuid", "payroc", "rfc", "json", "patchpricingintent", "put", "requires", "returns", "changes", "agent", "updating", "unique" ], "diagram": { "actors": [ { "id": "integrator", "name": "Integrator", "type": "client", "description": "Applies the JSON Patch; the only API caller in this workflow." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." } ], "steps": [ { "title": "Patch pricing intent", "label": "patch pricing intent", "badge": "REST · patch pricing intent", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "patchPricingIntent" } ] } }, "patch-an-event-subscription": { "workflowId": "patch-an-event-subscription", "domain": "notifications", "title": "Partially update an event subscription via PATCH.", "summary": "Partially update an event subscription via PATCH.", "stepCount": 1, "gotchas": [ "PATCH (patchEventSubscription) returns 200 with the updated body. Requires the Idempotency-Key header (UUID v4).", "The body is a JSON Patch array of `op`/`path`/`value` operations, NOT a plain resource object.", "The subscriptionId is the int64 id returned by create at `#/id`." ], "operationIds": [ "patchEventSubscription" ], "workflowRefs": [], "keywords": [ "idempotencykey", "idempotency", "key", "subscriptionid", "uuid", "rfc", "json", "patcheventsubscription", "put", "sent", "requires", "returns", "applies", "agent", "unique", "generate" ], "diagram": { "actors": [ { "id": "integrator", "name": "Integrator", "type": "client", "description": "Applies the JSON Patch; the only API caller in this workflow." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." } ], "steps": [ { "title": "Patch subscription", "label": "patch event subscription", "badge": "REST · patch event subscription", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "patchEventSubscription" } ] } }, "pay-with-single-use-token": { "workflowId": "pay-with-single-use-token", "domain": "payments", "title": "Create a single-use token, run a payment, optionally reverse it", "summary": "Create a single-use token, run a payment, optionally reverse it", "stepCount": 3, "gotchas": [], "operationIds": [ "createSingleUseToken", "payment", "reversePayment" ], "workflowRefs": [], "keywords": [ "web", "pos", "moto", "jane", "sarah", "hazel", "hopper", "orderref6543", "order", "ref6543", "large", "pepperoni", "pizza", "usd", "9abc", "8bcd" ], "diagram": { "actors": [ { "id": "customer", "name": "Customer", "type": "human", "description": "Cardholder who presents the payment card to be tokenized and charged." }, { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "Calls the Payroc API on the customer's behalf." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." }, { "id": "processor", "name": "Payment processor", "type": "external-system", "description": "Downstream processor that authorizes and settles the payment; not directly callable." } ], "steps": [ { "title": "Create single use token", "label": "single-use token request", "badge": "REST · single-use token request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "createSingleUseToken" }, { "title": "Run payment", "label": "payment request", "badge": "REST · payment request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "payment" }, { "title": "Reverse payment", "label": "reversal request", "badge": "REST · reversal request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "reversePayment" } ] } }, "reactivate-a-subscription": { "workflowId": "reactivate-a-subscription", "domain": "payments", "title": "Reactivate a subscription to resume collection.", "summary": "Reactivate a subscription to resume collection.", "stepCount": 1, "gotchas": [ "`subscriptionId` is the merchant-assigned string (for example `SubRef7654`) used on create, not a gateway-generated id.", "`reactivateSubscription` requires no request body and no Idempotency-Key header." ], "operationIds": [ "reactivateSubscription" ], "workflowRefs": [], "keywords": [ "subref7654", "sub", "ref7654", "processingterminalid", "processing", "terminal", "subscriptionid", "reactivatesubscription", "post", "idempotency", "key", "returns", "agent", "unique", "identifier", "owns" ], "diagram": { "actors": [ { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "Calls the Payroc API to resume collection for the subscription." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." } ], "steps": [ { "title": "Reactivate subscription", "label": "reactivate request", "badge": "REST · reactivate request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "reactivateSubscription" } ] } }, "refresh-a-saved-payment-method": { "workflowId": "refresh-a-saved-payment-method", "domain": "payments", "title": "List, retrieve, then refresh a secure token from a single-use token.", "summary": "List, retrieve, then refresh a secure token from a single-use token.", "stepCount": 3, "gotchas": [ "`accountUpdate` (POST .../update-account) body is `{ type: singleUseToken, token: <128-char token> }`. Requires a unique `Idempotency-Key` header. Returns 200 (not 201).", "The path parameter is the `secureTokenId` (format `MREF_...`)." ], "operationIds": [ "listSecureTokens", "getSecureToken", "accountUpdate" ], "workflowRefs": [], "keywords": [ "mref", "sarah", "20hazel", "hazel", "20hopper", "hopper", "processingterminalid", "processing", "terminal", "securetokenid", "customername", "customer", "name", "limit", "idempotencykey", "idempotency" ], "diagram": { "actors": [ { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "Calls the Payroc API to find the secure token and refresh its stored details." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." } ], "steps": [ { "title": "List secure tokens", "label": "token search", "badge": "REST · token search", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "listSecureTokens" }, { "title": "Get secure token", "label": "token lookup", "badge": "REST · token lookup", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "getSecureToken" }, { "title": "Account update", "label": "account update request", "badge": "REST · account update request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "accountUpdate" } ] } }, "refund-a-bank-transfer-payment": { "workflowId": "refund-a-bank-transfer-payment", "domain": "payments", "title": "Referenced refund of an existing bank-transfer / ACH payment.", "summary": "Referenced refund of an existing bank-transfer / ACH payment.", "stepCount": 3, "gotchas": [ "a referenced refund is a POST that returns 200 (not 201). Every refund POST requires an `Idempotency-Key` header in UUID v4 format. A refund only settles when the original payment is in a closed batch; if the payment is still in an open batch the gateway reverses (cancels) it instead of refunding - so this same endpoint doubles as a reversal, and a dedicated reverse endpoint is not needed. Both full and partial refunds use the same request; a partial refund simply sends an `amount` lower than the original payment amount." ], "operationIds": [ "listBankTransferPayments", "getBankTransferPayment", "refundBankTransferPayment" ], "workflowRefs": [], "keywords": [ "m2mjog6o2y", "mjog6", "orderref6543", "order", "ref6543", "idempotencykey", "idempotency", "key", "paymentid", "processingterminalid", "processing", "terminal", "orderid", "amount", "description", "uuid" ], "diagram": { "actors": [ { "id": "customer", "name": "Customer", "type": "human", "description": "The person who requested the refund and receives the returned funds to their bank account." }, { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "Calls the Payroc API to look up the payment and issue the refund on the customer's behalf." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." }, { "id": "processor", "name": "ACH network", "type": "external-system", "description": "Downstream ACH network that settles the returned funds; not directly callable." } ], "steps": [ { "title": "Find bank payment", "label": "payment search", "badge": "REST · payment search", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "listBankTransferPayments" }, { "title": "Get bank payment", "label": "payment lookup", "badge": "REST · payment lookup", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "getBankTransferPayment" }, { "title": "Refund bank payment", "label": "refund request", "badge": "REST · refund request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "refundBankTransferPayment" } ] } }, "refund-a-card-payment": { "workflowId": "refund-a-card-payment", "domain": "payments", "title": "Referenced refund of an existing card payment.", "summary": "Referenced refund of an existing card payment.", "stepCount": 3, "gotchas": [ "a referenced refund is a POST that returns 200 (not 201). The card refund id is nested, not top-level - it lives at `refunds/0/refundId`, not at the body root. Every refund POST requires an `Idempotency-Key` header in UUID v4 format. A refund only settles when the original payment is in a closed batch; if the payment is still in an open batch the gateway reverses (cancels) it instead of refunding - so this same endpoint doubles as a reversal, and a dedicated reverse endpoint is not needed. Both full and partial refunds use the same request; a partial refund simply sends an `amount` lower than the original payment amount." ], "operationIds": [ "listPayments", "getPayment", "refundPayment" ], "workflowRefs": [], "keywords": [ "m2mjog6o2y", "mjog6", "orderref6543", "order", "ref6543", "jane", "idempotencykey", "idempotency", "key", "paymentid", "processingterminalid", "processing", "terminal", "orderid", "amount", "description" ], "diagram": { "actors": [ { "id": "customer", "name": "Customer", "type": "human", "description": "The person who requested the refund and receives the returned funds to their card." }, { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "Calls the Payroc API to look up the payment and issue the refund on the customer's behalf." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." }, { "id": "processor", "name": "Payment processor", "type": "external-system", "description": "Downstream card processor that settles the returned funds; not directly callable." } ], "steps": [ { "title": "Find card payment", "label": "payment search", "badge": "REST · payment search", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "listPayments" }, { "title": "Get card payment", "label": "payment lookup", "badge": "REST · payment lookup", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "getPayment" }, { "title": "Refund card payment", "label": "refund request", "badge": "REST · refund request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "refundPayment" } ] } }, "refund-on-a-device": { "workflowId": "refund-on-a-device", "domain": "payroc-cloud", "title": "Submit a refund instruction to a device, poll it to completion, and retrieve the refund.", "summary": "Submit a refund instruction to a device, poll it to completion, and retrieve the refund.", "stepCount": 3, "gotchas": [], "operationIds": [ "sendRefundInstruction", "getRefundInstruction", "getRefund" ], "workflowRefs": [], "keywords": [ "jane", "orderref6543", "order", "ref6543", "usd", "cd3hn88u9f", "cd3", "hn88", "idempotencykey", "idempotency", "key", "serialnumber", "serial", "number", "processingterminalid", "processing" ], "diagram": { "actors": [ { "id": "cardholder", "name": "Cardholder", "type": "human", "description": "Cardholder present at the payment device who receives the returned funds." }, { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "POS integration that calls the Payroc API to drive and monitor the refund." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." }, { "id": "payment-device", "name": "Payroc Cloud payment device", "type": "external-system", "description": "Physical device (addressed by serialNumber) that executes the instruction with the downstream processor; not directly callable as an API step." } ], "steps": [ { "title": "Send refund instruction", "label": "refund instruction", "badge": "REST · refund instruction", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "sendRefundInstruction" }, { "title": "Get refund instruction", "label": "instruction status poll", "badge": "REST · instruction status poll", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "getRefundInstruction" }, { "title": "Get refund", "label": "refund retrieval", "badge": "REST · refund retrieval", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "getRefund" } ] } }, "replace-a-pricing-intent": { "workflowId": "replace-a-pricing-intent", "domain": "boarding", "title": "Fully replace a pricing intent via PUT.", "summary": "Fully replace a pricing intent via PUT.", "stepCount": 1, "gotchas": [ "The write payload is MPA version 5.2 (`writePricingIntent`); `country`, `version`, `base`, and `key` are required. Fee amounts are integers in the currency's lowest denomination (cents).", "PUT returns 204 No Content (no body).", "Updating a pricing intent never affects merchants you have already onboarded; it only changes the template for future assignments." ], "operationIds": [ "updatePricingIntent" ], "workflowRefs": [], "keywords": [ "unique", "identifier", "pricingintentid", "key", "payroc", "mpa", "updatepricingintent", "update", "content", "writepricingintent", "write", "rfc", "json", "patch", "returns", "overwrites" ], "diagram": { "actors": [ { "id": "integrator", "name": "Integrator", "type": "client", "description": "Replaces the pricing intent; the only API caller in this workflow." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." } ], "steps": [ { "title": "Replace pricing intent", "label": "replace pricing intent", "badge": "REST · replace pricing intent", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "updatePricingIntent" } ] } }, "represent-ach-payment": { "workflowId": "represent-ach-payment", "domain": "payments", "title": "Retrieve an ACH return reason and re-present the payment.", "summary": "Retrieve an ACH return reason and re-present the payment.", "stepCount": 2, "gotchas": [], "operationIds": [ "getBankTransferPayment", "representBankTransferPayment" ], "workflowRefs": [], "keywords": [ "e29u8ou8q4", "e29", "ou8", "sarah", "hazel", "hopper", "web", "paymentid", "idempotencykey", "idempotency", "key", "nameonaccount", "name", "account", "accountnumber", "number" ], "diagram": { "actors": [ { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "Calls the Payroc API to read the return reason and re-present the payment." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." }, { "id": "ach-network", "name": "ACH network", "type": "external-system", "description": "Returned the original bank-transfer payment; the re-presented payment is resubmitted to it for collection. Not directly callable." } ], "steps": [ { "title": "View payment", "label": "payment lookup", "badge": "REST · payment lookup", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "getBankTransferPayment" }, { "title": "Represent payment", "label": "re-presentment request", "badge": "REST · re-presentment request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "representBankTransferPayment" } ] } }, "reverse-a-bank-transfer-payment": { "workflowId": "reverse-a-bank-transfer-payment", "domain": "payments", "title": "Look up and reverse a bank-transfer payment in an open batch.", "summary": "Look up and reverse a bank-transfer payment in an open batch.", "stepCount": 2, "gotchas": [], "operationIds": [ "listBankTransferPayments", "reverseBankTransferPayment" ], "workflowRefs": [], "keywords": [ "orderref6543", "order", "ref6543", "m2mjog6o2y", "mjog6", "processingterminalid", "processing", "terminal", "orderid", "paymentid", "idempotencykey", "idempotency", "key", "uuid", "listbanktransferpayments", "list" ], "diagram": { "actors": [ { "id": "customer", "name": "Customer", "type": "human", "description": "Account holder who requested that the payment be canceled." }, { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "Calls the Payroc API to look up and reverse the payment." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." }, { "id": "processor", "name": "Payment processor", "type": "external-system", "description": "Downstream processor that clears the open batch; not directly callable." } ], "steps": [ { "title": "List bank transfer payments", "label": "payment search", "badge": "REST · payment search", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "listBankTransferPayments" }, { "title": "Reverse bank transfer payment", "label": "reversal request", "badge": "REST · reversal request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "reverseBankTransferPayment" } ] } }, "reverse-a-bank-transfer-refund": { "workflowId": "reverse-a-bank-transfer-refund", "domain": "payments", "title": "List, retrieve, then reverse (cancel) a bank-transfer refund.", "summary": "List, retrieve, then reverse (cancel) a bank-transfer refund.", "stepCount": 3, "gotchas": [], "operationIds": [ "listBankTransferRefunds", "getBankTransferRefund", "reverseBankTransferRefund" ], "workflowRefs": [], "keywords": [ "orderref6543", "order", "ref6543", "ready", "01t15", "t15", "00z", "processingterminalid", "processing", "terminal", "orderid", "status", "datefrom", "date", "limit", "idempotencykey" ], "diagram": { "actors": [ { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "Calls the Payroc API to find, inspect, and reverse the refund." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." } ], "steps": [ { "title": "List bank transfer refunds", "label": "refund search", "badge": "REST · refund search", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "listBankTransferRefunds" }, { "title": "Get bank transfer refund", "label": "refund lookup", "badge": "REST · refund lookup", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "getBankTransferRefund" }, { "title": "Reverse bank transfer refund", "label": "reversal request", "badge": "REST · reversal request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "reverseBankTransferRefund" } ] } }, "reverse-a-card-payment": { "workflowId": "reverse-a-card-payment", "domain": "payments", "title": "Look up and reverse a card payment in an open batch.", "summary": "Look up and reverse a card payment in an open batch.", "stepCount": 2, "gotchas": [], "operationIds": [ "listPayments", "reversePayment" ], "workflowRefs": [], "keywords": [ "orderref6543", "order", "ref6543", "m2mjog6o2y", "mjog6", "jane", "processingterminalid", "processing", "terminal", "orderid", "paymentid", "idempotencykey", "idempotency", "key", "operator", "amount" ], "diagram": { "actors": [ { "id": "customer", "name": "Customer", "type": "human", "description": "Cardholder who requested that the payment be canceled." }, { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "Calls the Payroc API to look up and reverse the payment." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." }, { "id": "processor", "name": "Payment processor", "type": "external-system", "description": "Downstream processor that clears the open batch; not directly callable." } ], "steps": [ { "title": "List payments", "label": "payment search", "badge": "REST · payment search", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "listPayments" }, { "title": "Reverse card payment", "label": "reversal request", "badge": "REST · reversal request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "reversePayment" } ] } }, "reverse-a-refund": { "workflowId": "reverse-a-refund", "domain": "payments", "title": "List, retrieve, then reverse (cancel) a card refund.", "summary": "List, retrieve, then reverse (cancel) a card refund.", "stepCount": 3, "gotchas": [], "operationIds": [ "listRefunds", "getRefund", "reverseRefund" ], "workflowRefs": [], "keywords": [ "orderref6543", "order", "ref6543", "ready", "01t15", "t15", "00z", "processingterminalid", "processing", "terminal", "orderid", "status", "datefrom", "date", "limit", "idempotencykey" ], "diagram": { "actors": [ { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "Calls the Payroc API to find, inspect, and reverse the refund." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." } ], "steps": [ { "title": "List refunds", "label": "refund search", "badge": "REST · refund search", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "listRefunds" }, { "title": "Get refund", "label": "refund lookup", "badge": "REST · refund lookup", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "getRefund" }, { "title": "Reverse refund", "label": "reversal request", "badge": "REST · reversal request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "reverseRefund" } ] } }, "review-funding-activity": { "workflowId": "review-funding-activity", "domain": "funding", "title": "Read funding balances then the funding activity ledger.", "summary": "Read funding balances then the funding activity ledger.", "stepCount": 2, "gotchas": [], "operationIds": [ "getFundingBalance", "getFundingActivity" ], "workflowRefs": [], "keywords": [ "merchantid", "merchant", "datefrom", "date", "dateto", "limit", "yyyy", "gets", "getfundingactivity", "get", "filter", "omit", "maximum", "step", "both", "optional" ], "diagram": { "actors": [ { "id": "integrator", "name": "Integrator", "type": "client", "description": "Payfac integrator reviewing balances and activity; the only API caller in this workflow." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." } ], "steps": [ { "title": "Get funding balance", "label": "get funding balances", "badge": "REST · get funding balances", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "getFundingBalance" }, { "title": "Get funding activity", "label": "get funding activity", "badge": "REST · get funding activity", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "getFundingActivity" } ] } }, "review-merchant-hierarchy": { "workflowId": "review-merchant-hierarchy", "domain": "boarding", "title": "Confirm a boarded merchant's hierarchy and status via read-only reads.", "summary": "Confirm a boarded merchant's hierarchy and status via read-only reads.", "stepCount": 10, "gotchas": [], "operationIds": [ "listMerchantPlatforms", "getMerchantAccounts", "listMerchantLocations", "getProcessingAccounts", "retrieveProcessingAccountPricing", "listProcessingAccountContacts", "listMerchantOwners", "listProcessingAccountsFundingAccounts", "listProcessingAccountsTerminalOrders", "listProcessingAccountsProcessingTerminals" ], "workflowRefs": [], "keywords": [ "limit", "processingaccountid", "processing", "account", "isv", "get", "retrieveprocessingaccount", "retrieve", "steps", "starting", "use", "every", "two", "maximum", "number", "results" ], "diagram": { "actors": [ { "id": "integrator", "name": "Integrator", "type": "client", "description": "Runs the read-only traversal; the only API caller in this workflow." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." } ], "steps": [ { "title": "List merchant platforms", "label": "list merchant platforms", "badge": "REST · list merchant platforms", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "listMerchantPlatforms" }, { "title": "Retrieve merchant platform", "label": "get merchant platform", "badge": "REST · get merchant platform", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "getMerchantAccounts" }, { "title": "List platform processing accounts", "label": "list processing accounts", "badge": "REST · list processing accounts", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "listMerchantLocations" }, { "title": "Retrieve processing account", "label": "get processing account", "badge": "REST · get processing account", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "getProcessingAccounts" }, { "title": "Retrieve processing account pricing", "label": "get pricing agreement", "badge": "REST · get pricing agreement", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "retrieveProcessingAccountPricing" }, { "title": "List processing account contacts", "label": "list contacts", "badge": "REST · list contacts", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "listProcessingAccountContacts" }, { "title": "List merchant owners", "label": "list owners", "badge": "REST · list owners", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "listMerchantOwners" }, { "title": "List processing account funding accounts", "label": "list funding accounts", "badge": "REST · list funding accounts", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "listProcessingAccountsFundingAccounts" }, { "title": "List processing account terminal orders", "label": "list terminal orders", "badge": "REST · list terminal orders", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "listProcessingAccountsTerminalOrders" }, { "title": "List processing account processing terminals", "label": "list processing terminals", "badge": "REST · list processing terminals", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "listProcessingAccountsProcessingTerminals" } ] } }, "review-settlement-reporting": { "workflowId": "review-settlement-reporting", "domain": "reporting", "title": "List then drill into settlement reports across five report types.", "summary": "List then drill into settlement reports across five report types.", "stepCount": 11, "gotchas": [ "identifiers here are integers (`batchId`, `transactionId`, `authorizationId`, `disputeId`, `achDepositId`), unlike the string `merchantId` the processor assigns. `getbatches`, `getdisputes`, and `getAchDeposits` require the `date` query parameter. `getTransactions` and `getAuthorizations` require EITHER `date` OR `batchId`. `getAchDepositFees` requires EITHER `date` OR `achDepositId`. All list steps accept an optional `merchantId` filter and `before`/`after`/`limit` pagination. The list -> retrieve steps within a branch chain by feeding the first list row's id into the retrieve step; supply the id directly if you already have it." ], "operationIds": [ "getbatches", "getbatch", "getTransactions", "gettransaction", "getAuthorizations", "getAuthorization", "getdisputes", "getdisputesStatuses", "getAchDeposits", "getAchDeposit", "getAchDepositFees" ], "workflowRefs": [], "keywords": [ "date", "merchantid", "merchant", "limit", "yyyy", "ach", "getachdeposits", "get", "deposits", "gettransactions", "transactions", "getauthorizations", "authorizations", "batchid", "batch", "getachdepositfees" ], "diagram": { "actors": [ { "id": "integrator", "name": "Integrator", "type": "client", "description": "Reads the settlement reports; the only API caller in this workflow." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." } ], "steps": [ { "title": "List batches", "label": "list batches", "badge": "REST · list batches", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "getbatches" }, { "title": "Retrieve batch", "label": "get batch", "badge": "REST · get batch", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "getbatch" }, { "title": "List transactions", "label": "list transactions", "badge": "REST · list transactions", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "getTransactions" }, { "title": "Retrieve transaction", "label": "get transaction", "badge": "REST · get transaction", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "gettransaction" }, { "title": "List authorizations", "label": "list authorizations", "badge": "REST · list authorizations", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "getAuthorizations" }, { "title": "Retrieve authorization", "label": "get authorization", "badge": "REST · get authorization", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "getAuthorization" }, { "title": "List disputes", "label": "list disputes", "badge": "REST · list disputes", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "getdisputes" }, { "title": "List dispute statuses", "label": "list dispute statuses", "badge": "REST · list dispute statuses", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "getdisputesStatuses" }, { "title": "List ACH deposits", "label": "list ACH deposits", "badge": "REST · list ACH deposits", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "getAchDeposits" }, { "title": "Retrieve ACH deposit", "label": "get ACH deposit", "badge": "REST · get ACH deposit", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "getAchDeposit" }, { "title": "List ACH deposit fees", "label": "list ACH deposit fees", "badge": "REST · list ACH deposit fees", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "getAchDepositFees" } ] } }, "run-a-bank-transfer-sale": { "workflowId": "run-a-bank-transfer-sale", "domain": "payments", "title": "Run a bank-transfer (ACH/PAD) sale.", "summary": "Run a bank-transfer (ACH/PAD) sale.", "stepCount": 1, "gotchas": [], "operationIds": [ "bankTransferPayment" ], "workflowRefs": [], "keywords": [ "orderref6543", "order", "ref6543", "large", "pepperoni", "pizza", "usd", "checking", "sarah", "hazel", "hopper", "idempotencykey", "idempotency", "key", "processingterminalid", "processing" ], "diagram": { "actors": [ { "id": "customer", "name": "Customer", "type": "human", "description": "Account holder who presents the payment method." }, { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "Calls the Payroc API on the customer's behalf." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." }, { "id": "processor", "name": "Payment processor", "type": "external-system", "description": "Downstream ACH network that authorizes the funds; not directly callable." } ], "steps": [ { "title": "Run bank transfer sale", "label": "bank-transfer sale request", "badge": "REST · bank-transfer sale request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "bankTransferPayment" } ] } }, "run-a-card-sale": { "workflowId": "run-a-card-sale", "domain": "payments", "title": "Run a card sale.", "summary": "Run a card sale.", "stepCount": 1, "gotchas": [], "operationIds": [ "payment" ], "workflowRefs": [], "keywords": [ "jane", "orderref6543", "order", "ref6543", "large", "pepperoni", "pizza", "usd", "idempotencykey", "idempotency", "key", "processingterminalid", "processing", "terminal", "operator", "orderid" ], "diagram": { "actors": [ { "id": "customer", "name": "Customer", "type": "human", "description": "Cardholder who presents the payment method." }, { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "Calls the Payroc API on the customer's behalf." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." }, { "id": "processor", "name": "Payment processor", "type": "external-system", "description": "Downstream processor / card scheme that authorizes the funds; not directly callable." } ], "steps": [ { "title": "Run card sale", "label": "sale request", "badge": "REST · sale request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "payment" } ] } }, "run-a-pre-authorization": { "workflowId": "run-a-pre-authorization", "domain": "payments", "title": "Pre-authorize a card, optionally adjust the amount, capture, and optionally refund.", "summary": "Pre-authorize a card, optionally adjust the amount, capture, and optionally refund.", "stepCount": 4, "gotchas": [ "To run a pre-authorization (rather than a sale), send BOTH `autoCapture: false` AND `processAsSale: false` in the Create Payment body. If either is true the gateway runs a sale, and a sale cannot be captured. If `processAsSale` is true the gateway ignores `autoCapture` entirely.", "This flow is state-dependent: only an open pre-authorization can be captured. Pre-authorizations must be enabled on the merchant's account; if they are not, the gateway runs the request as a sale with status `pending`.", "Adjust (step 2) is optional and is how you capture MORE than you originally authorized (card brands cap the additional amount): adjust up first, then capture. Capturing less needs no adjust - just send a smaller `amount` on capture, or omit `amount` to capture the full authorized amount.", "Refund (step 4) is optional and only applies AFTER capture, once the batch is closed. If the payment is still in an open batch, `refundPayment` reverses it instead of refunding. Reversal (void) is a distinct operation - do not conflate refund with reversal.", "Every operation requires a unique `Idempotency-Key` header (UUID v4). Use a fresh key per request; reusing a key replays the original response." ], "operationIds": [ "payment", "adjustPayment", "capturePayment", "refundPayment" ], "workflowRefs": [], "keywords": [ "9abc", "8bcd", "9cde", "jane", "orderref6543", "order", "ref6543", "usd", "pizza", "doe", "dinner", "paymentidempotencykey", "payment", "idempotency", "key", "adjustidempotencykey" ], "diagram": { "actors": [ { "id": "customer", "name": "Customer", "type": "human", "description": "Cardholder who presents the payment card to be pre-authorized and later charged." }, { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "Calls the Payroc API on the customer's behalf to authorize, adjust, capture, and refund." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." }, { "id": "processor", "name": "Payment processor", "type": "external-system", "description": "Downstream card processor and issuing bank that hold and release the funds; not directly callable." } ], "steps": [ { "title": "Create pre authorization", "label": "pre-authorization request", "badge": "REST · pre-authorization request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "payment" }, { "title": "Adjust authorized amount", "label": "adjustment request", "badge": "REST · adjustment request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "adjustPayment" }, { "title": "Capture pre authorization", "label": "capture request", "badge": "REST · capture request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "capturePayment" }, { "title": "Refund captured payment", "label": "refund request", "badge": "REST · refund request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "refundPayment" } ] } }, "run-a-sale-on-a-device": { "workflowId": "run-a-sale-on-a-device", "domain": "payroc-cloud", "title": "Find a device, push a sale instruction, poll for the result, and retrieve the payment.", "summary": "Find a device, push a sale instruction, poll for the result, and retrieve the payment.", "stepCount": 4, "gotchas": [], "operationIds": [ "searchDevices", "sendPaymentInstruction", "getPaymentInstruction", "getPayment" ], "workflowRefs": [], "keywords": [ "jane", "orderref6543", "order", "ref6543", "usd", "m2mjog6o2y", "mjog6", "idempotencykey", "idempotency", "key", "serialnumber", "serial", "number", "processingterminalid", "processing", "terminal" ], "diagram": { "actors": [ { "id": "cardholder", "name": "Cardholder", "type": "human", "description": "Cardholder who taps, inserts, or swipes their card on the payment device." }, { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "The POS integration calling the Payroc API to drive the device." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call; relays instructions to the device." }, { "id": "payment-device", "name": "Payroc Cloud payment device", "type": "external-system", "description": "Physical Payroc Cloud terminal that captures the card and completes the sale; reached via the gateway, not called directly." } ], "steps": [ { "title": "Find device", "label": "device lookup", "badge": "REST · device lookup", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "searchDevices" }, { "title": "Submit payment instruction", "label": "payment instruction", "badge": "REST · payment instruction", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "sendPaymentInstruction" }, { "title": "Poll payment instruction", "label": "instruction status poll", "badge": "REST · instruction status poll", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "getPaymentInstruction" }, { "title": "Retrieve payment", "label": "payment retrieval", "badge": "REST · payment retrieval", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "getPayment" } ] } }, "run-unreferenced-bank-transfer-refund": { "workflowId": "run-unreferenced-bank-transfer-refund", "domain": "payments", "title": "Refund a customer's bank account (ACH) with no originating payment reference.", "summary": "Refund a customer's bank account (ACH) with no originating payment reference.", "stepCount": 1, "gotchas": [ "the refund id is returned at the top level as `refundId` (not nested); every request requires an `Idempotency-Key` header in UUID v4 format; and `refundMethod` is polymorphic - its `type` (ach / secureToken) selects the variant, so do not mix card fields into an ACH refund." ], "operationIds": [ "bankTransferUnreferencedRefund" ], "workflowRefs": [], "keywords": [ "orderref6543", "order", "ref6543", "usd", "sarah", "hazel", "hopper", "example", "com", "idempotencykey", "idempotency", "key", "processingterminalid", "processing", "terminal", "orderid" ], "diagram": { "actors": [ { "id": "customer", "name": "Customer", "type": "human", "description": "The person receiving the returned funds to their bank account." }, { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "Calls the Payroc API to issue the unreferenced refund on the customer's behalf." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." }, { "id": "processor", "name": "ACH network", "type": "external-system", "description": "Downstream ACH network that settles the returned funds; not directly callable." } ], "steps": [ { "title": "Run bank refund", "label": "unreferenced refund request", "badge": "REST · unreferenced refund request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "bankTransferUnreferencedRefund" } ] } }, "run-unreferenced-card-refund": { "workflowId": "run-unreferenced-card-refund", "domain": "payments", "title": "Refund a customer's card with no originating payment reference.", "summary": "Refund a customer's card with no originating payment reference.", "stepCount": 1, "gotchas": [ "the refund id is returned at the top level as `refundId` (not nested); every request requires an `Idempotency-Key` header in UUID v4 format; and `refundMethod` is polymorphic - its `type` (card / secureToken) selects the variant, so do not mix ACH fields into a card refund." ], "operationIds": [ "unreferencedRefund" ], "workflowRefs": [], "keywords": [ "jane", "orderref6543", "order", "ref6543", "usd", "pos", "idempotencykey", "idempotency", "key", "processingterminalid", "processing", "terminal", "operator", "orderid", "description", "amount" ], "diagram": { "actors": [ { "id": "customer", "name": "Customer", "type": "human", "description": "The person receiving the returned funds to their card." }, { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "Calls the Payroc API to issue the unreferenced refund on the customer's behalf." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." }, { "id": "processor", "name": "Payment processor", "type": "external-system", "description": "Downstream card processor that settles the returned funds; not directly callable." } ], "steps": [ { "title": "Run card refund", "label": "unreferenced refund request", "badge": "REST · unreferenced refund request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "unreferencedRefund" } ] } }, "save-a-card-with-hosted-fields": { "workflowId": "save-a-card-with-hosted-fields", "domain": "payments", "title": "Create a tokenization session, tokenize card details client-side, then mint a reusable secure token.", "summary": "Create a tokenization session, tokenize card details client-side, then mint a reusable secure token.", "stepCount": 3, "gotchas": [], "operationIds": [ "createSession", "createSecureToken" ], "workflowRefs": [], "keywords": [ "jane", "1a2b", "4c3d", "9e5f", "mref", "recurring", "processingterminalid", "processing", "terminal", "sessionidempotencykey", "idempotency", "key", "libversion", "lib", "version", "singleusetoken" ], "diagram": { "actors": [ { "id": "customer", "name": "Customer", "type": "human", "description": "Cardholder who enters their payment details into the Hosted Fields form." }, { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "Hosts the checkout page and calls the Payroc API server-side to create the session and save the card." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call; also hosts the embedded fields and issues the single-use token." } ], "steps": [ { "title": "Create hosted fields session", "label": "session request", "badge": "REST · session request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "createSession" }, { "title": "Customer submits payment details", "label": "hosted fields submit", "badge": "hosted fields submit · not REST", "actorId": "customer", "actorToId": "payroc-gateway" }, { "title": "Save card from token", "label": "secure token request", "badge": "REST · secure token request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "createSecureToken" } ] } }, "save-a-payment-method": { "workflowId": "save-a-payment-method", "domain": "payments", "title": "Create a reusable secure token from a customer's card or bank account.", "summary": "Create a reusable secure token from a customer's card or bank account.", "stepCount": 1, "gotchas": [], "operationIds": [ "createSecureToken" ], "workflowRefs": [], "keywords": [ "mref", "jane", "recurring", "sarah", "hopper", "example", "com", "hazel", "processingterminalid", "processing", "terminal", "idempotencykey", "idempotency", "key", "securetokenid", "operator" ], "diagram": { "actors": [ { "id": "customer", "name": "Customer", "type": "human", "description": "Cardholder / account holder who presents the payment details to be saved." }, { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "Calls the Payroc API on the customer's behalf to vault the details." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface that stores the details and returns the secure token." } ], "steps": [ { "title": "Create secure token", "label": "secure token request", "badge": "REST · secure token request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "createSecureToken" } ] } }, "send-funds-to-a-merchant": { "workflowId": "send-funds-to-a-merchant", "domain": "funding", "title": "Create a funding recipient, optionally check the balance, then send funds via a funding instruction.", "summary": "Create a funding recipient, optionally check the balance, then send funds via a funding instruction.", "stepCount": 3, "gotchas": [ "amounts are integers in the currency's lowest denomination (cents), not decimals; paymentMethod is the fixed enum ACH; the destination is a fundingAccountId (the recipient's credit funding account), not the recipientId or the merchantId; getFundingBalance reports funds, pending, and available separately - only the available amount can be distributed; the balance check is OPTIONAL. Every write requires a unique Idempotency-Key header in UUID v4 format." ], "operationIds": [ "getFundingBalance", "createInstruction" ], "workflowRefs": [ "set-up-a-funding-recipient" ], "keywords": [ "privatecorporation", "private", "corporation", "pizza", "doe", "jane", "example", "com", "merchantid", "recipienttype", "type", "taxid", "tax", "doingbusinessas", "doing", "business" ], "diagram": { "actors": [ { "id": "integrator", "name": "Integrator", "type": "client", "description": "Sets up the recipient, checks the balance, and issues the funding instruction; the only API caller in this workflow." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." }, { "id": "recipient", "name": "Funding recipient", "type": "external-system", "description": "Business or organization whose credit funding account receives the distributed funds by ACH; not an API caller." } ], "steps": [ { "title": "Set up recipient", "label": "set up funding recipient", "badge": "Workflow · set up funding recipient", "actorId": "integrator", "actorToId": "payroc-gateway", "workflowRef": "set-up-a-funding-recipient" }, { "title": "Check balance", "label": "check available balance", "badge": "REST · check available balance", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "getFundingBalance" }, { "title": "Create instruction", "label": "create funding instruction", "badge": "REST · create funding instruction", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "createInstruction" } ] } }, "set-up-a-funding-recipient": { "workflowId": "set-up-a-funding-recipient", "domain": "funding", "title": "Create a funding recipient, then optionally add extra accounts and owners.", "summary": "Create a funding recipient, then optionally add extra accounts and owners.", "stepCount": 3, "gotchas": [ "recipientType is a fixed enum (privateCorporation, nonProfit, soleProprietor, etc.); taxId is the EIN/SSN of the recipient; a funding account attached to a recipient accepts only use: credit (we send funds to it); the ACH paymentMethod routingNumber must be exactly 9 digits and the accountNumber 9-12 digits. Every write requires a unique Idempotency-Key header in UUID v4 format." ], "operationIds": [ "createFundingRecipient", "createFundRecipientFundingAccount", "createFundRecipientOwner" ], "workflowRefs": [], "keywords": [ "privatecorporation", "private", "corporation", "pizza", "doe", "jane", "example", "com", "recipienttype", "type", "taxid", "tax", "doingbusinessas", "doing", "business", "contactemail" ], "diagram": { "actors": [ { "id": "integrator", "name": "Integrator", "type": "client", "description": "Creates the funding recipient and its accounts and owners; the only API caller in this workflow." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." } ], "steps": [ { "title": "Create funding recipient", "label": "create funding recipient", "badge": "REST · create funding recipient", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "createFundingRecipient" }, { "title": "Add funding account", "label": "add funding account", "badge": "REST · add funding account", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "createFundRecipientFundingAccount" }, { "title": "Add owner", "label": "add owner", "badge": "REST · add owner", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "createFundRecipientOwner" } ] } }, "set-up-repeat-payments": { "workflowId": "set-up-repeat-payments", "domain": "payments", "title": "Create a payment plan, save the customer's payment method, then subscribe the customer to the plan.", "summary": "Create a payment plan, save the customer's payment method, then subscribe the customer to the plan.", "stepCount": 3, "gotchas": [], "operationIds": [], "workflowRefs": [ "manage-payment-plans", "save-a-payment-method", "manage-subscriptions" ], "keywords": [ "9abc", "8bcd", "planref8765", "ref8765", "premium", "club", "usd", "monthly", "subref7654", "sub", "ref7654", "mref", "jane", "sarah", "hopper", "example" ], "diagram": { "actors": [ { "id": "customer", "name": "Customer", "type": "human", "description": "Cardholder who agrees to recurring billing and supplies the payment method to be stored." }, { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "Calls the Payroc API to build the plan, save the token, and create the subscription on the customer's behalf." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call; for an automatic plan it also schedules and collects each recurring payment." }, { "id": "processor", "name": "Payment processor", "type": "external-system", "description": "Downstream processor behind the gateway that settles each collected payment; not directly callable." } ], "steps": [ { "title": "Set up payment plan", "label": "create plan request", "badge": "Workflow · create plan request", "actorId": "merchant", "actorToId": "payroc-gateway", "workflowRef": "manage-payment-plans" }, { "title": "Save payment method", "label": "secure token request", "badge": "Workflow · secure token request", "actorId": "customer", "actorToId": "payroc-gateway", "workflowRef": "save-a-payment-method" }, { "title": "Subscribe customer to plan", "label": "create subscription request", "badge": "Workflow · create subscription request", "actorId": "merchant", "actorToId": "payroc-gateway", "workflowRef": "manage-subscriptions" } ] } }, "update-a-contact": { "workflowId": "update-a-contact", "domain": "boarding", "title": "List, retrieve, then update (full PUT replace) a processing account's contact.", "summary": "List, retrieve, then update (full PUT replace) a processing account's contact.", "stepCount": 3, "gotchas": [ "contactId is an integer (e.g. 1543), not a string; it is issued by the gateway when the processing account is created and is also discoverable via the list step. updateContact is a full PUT replace (not a PATCH) against the contact schema — omitted fields are not preserved, so send the complete object. It returns 204 No Content. A contact must always carry at least one contact-number method (phone or mobile); email alone is insufficient." ], "operationIds": [ "listProcessingAccountContacts", "getContact", "updateContact" ], "workflowRefs": [], "keywords": [ "processingaccountid", "contactid", "limit", "listcontacts", "contacts", "getcontact", "get", "updatecontact", "patch", "content", "agent", "unique", "identifier", "gateway", "assigned", "integer" ], "diagram": { "actors": [ { "id": "integrator", "name": "Integrator", "type": "client", "description": "Finds and replaces the contact; the only API caller in this workflow." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." } ], "steps": [ { "title": "List contacts", "label": "list contacts", "badge": "REST · list contacts", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "listProcessingAccountContacts" }, { "title": "Get contact", "label": "get contact", "badge": "REST · get contact", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "getContact" }, { "title": "Update contact", "label": "replace contact", "badge": "REST · replace contact", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "updateContact" } ] } }, "update-a-funding-account": { "workflowId": "update-a-funding-account", "domain": "funding", "title": "List, retrieve, then update a funding account.", "summary": "List, retrieve, then update a funding account.", "stepCount": 3, "gotchas": [ "A funding account's fundingAccountId is an integer, not one of the alphanumeric ids used elsewhere in the API.", "Update only applies to a funding account associated with a FUNDING RECIPIENT. You cannot update a funding account associated with a processing account - the API rejects those. For a funding-recipient account, `use` must be `credit`.", "`updateFundingAccount` returns 204 No Content, so there is no response body to capture. All of type, use, nameOnAccount, and paymentMethods are required in the body." ], "operationIds": [ "listFundingAccount", "getFundingAccount", "updateFundingAccount" ], "workflowRefs": [], "keywords": [ "fundingaccountid", "limit", "listfundingaccounts", "accounts", "getfundingaccount", "get", "updatefundingaccount", "ach", "payroc", "api", "recipient", "content", "nameonaccount", "name", "paymentmethods", "payment" ], "diagram": { "actors": [ { "id": "integrator", "name": "Integrator", "type": "client", "description": "Finds and updates the funding account; the only API caller in this workflow." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." } ], "steps": [ { "title": "List funding accounts", "label": "list funding accounts", "badge": "REST · list funding accounts", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "listFundingAccount" }, { "title": "Get funding account", "label": "get funding account", "badge": "REST · get funding account", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "getFundingAccount" }, { "title": "Update funding account", "label": "update funding account", "badge": "REST · update funding account", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "updateFundingAccount" } ] } }, "update-a-funding-instruction": { "workflowId": "update-a-funding-instruction", "domain": "funding", "title": "List, retrieve, then update (replace) a funding instruction.", "summary": "List, retrieve, then update (replace) a funding instruction.", "stepCount": 3, "gotchas": [], "operationIds": [ "listInstructions", "getInstruction", "updateInstructions" ], "workflowRefs": [], "keywords": [ "usd", "instructioncreatedby", "created", "jane", "doe", "datefrom", "date", "dateto", "after", "limit", "instructionid", "merchantid", "merchant", "fundingaccountid", "account", "amountvalue" ], "diagram": { "actors": [ { "id": "integrator", "name": "Integrator", "type": "client", "description": "Finds and updates the funding instruction; the only API caller in this workflow." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." } ], "steps": [ { "title": "List instructions", "label": "list funding instructions", "badge": "REST · list funding instructions", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "listInstructions" }, { "title": "Get instruction", "label": "get funding instruction", "badge": "REST · get funding instruction", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "getInstruction" }, { "title": "Update instruction", "label": "update funding instruction", "badge": "REST · update funding instruction", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "updateInstructions" } ] } }, "update-a-funding-recipient": { "workflowId": "update-a-funding-recipient", "domain": "funding", "title": "List, retrieve, then update (full PUT) a funding recipient.", "summary": "List, retrieve, then update (full PUT) a funding recipient.", "stepCount": 3, "gotchas": [ "The path parameter is recipientId (an integer).", "updateFundingRecipient is a full-object PUT that returns 204 No Content (no body); it does not return the updated resource. Significant changes may trigger re-approval (status returns to pending).", "owners and fundingAccounts are read-only summaries echoed back in the payload from the retrieve step; the mutable fields are recipientType, taxId, charityId, doingBusinessAs, address, contactMethods, and metadata." ], "operationIds": [ "listFundingRecipients", "getFundingRecipient", "updateFundingRecipient" ], "workflowRefs": [], "keywords": [ "privatecorporation", "private", "corporation", "doe", "hot", "dogs", "fred", "nerk", "example", "com", "recipientid", "limit", "recipienttype", "type", "taxid", "tax" ], "diagram": { "actors": [ { "id": "integrator", "name": "Integrator", "type": "client", "description": "Finds and updates the funding recipient; the only API caller in this workflow." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." } ], "steps": [ { "title": "List recipients", "label": "list funding recipients", "badge": "REST · list funding recipients", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "listFundingRecipients" }, { "title": "Get recipient", "label": "get funding recipient", "badge": "REST · get funding recipient", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "getFundingRecipient" }, { "title": "Update recipient", "label": "update funding recipient", "badge": "REST · update funding recipient", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "updateFundingRecipient" } ] } }, "update-a-payment-plan": { "workflowId": "update-a-payment-plan", "domain": "payments", "title": "List, retrieve, then update a payment plan via JSON Patch.", "summary": "List, retrieve, then update a payment plan via JSON Patch.", "stepCount": 3, "gotchas": [ "`paymentPlanId` is merchant-assigned and is the `{paymentPlanId}` path parameter.", "`updatePaymentPlan` is a PATCH whose body is an RFC 6902 JSON Patch document (an array of `op`/`path`/`value` operations), NOT a plain plan object. Every property except `paymentPlanId` can be patched. Requires a unique `Idempotency-Key` header. Returns 200.", "Whether the change reaches existing subscriptions depends on the plan's `onUpdate` value (`update` vs `continue`), set at create time." ], "operationIds": [ "listPaymentPlans", "getPaymentPlan", "updatePaymentPlan" ], "workflowRefs": [], "keywords": [ "planref8765", "ref8765", "replace", "path", "setuporder", "setup", "order", "amount", "value", "frequency", "yearly", "processingterminalid", "processing", "terminal", "paymentplanid", "idempotencykey" ], "diagram": { "actors": [ { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "Calls the Payroc API to find and patch the payment plan." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." } ], "steps": [ { "title": "List payment plans", "label": "plan search", "badge": "REST · plan search", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "listPaymentPlans" }, { "title": "Get payment plan", "label": "plan lookup", "badge": "REST · plan lookup", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "getPaymentPlan" }, { "title": "Update payment plan", "label": "JSON Patch update", "badge": "REST · JSON Patch update", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "updatePaymentPlan" } ] } }, "update-a-saved-payment-method": { "workflowId": "update-a-saved-payment-method", "domain": "payments", "title": "List, retrieve, then update a secure token via JSON Patch.", "summary": "List, retrieve, then update a secure token via JSON Patch.", "stepCount": 3, "gotchas": [ "`secureTokenId` versus `token`. The path parameter is the `secureTokenId` (format `MREF_...`) — the durable handle. The `token` field on the resource is the short numeric value you replay in a transaction. They are different values.", "`updateSecureToken` (PATCH) body is an RFC 6902 JSON Patch document (an array of `op`/`path`/`value` operations), NOT a plain resource object. Immutable fields (processingTerminalId, type, token, status, and the sensitive source fields such as cardNumber/routingNumber) cannot be patched. Requires a unique `Idempotency-Key` header. Returns 200." ], "operationIds": [ "listSecureTokens", "getSecureToken", "updateSecureToken" ], "workflowRefs": [], "keywords": [ "mref", "sarah", "20hazel", "hazel", "20hopper", "hopper", "replace", "path", "customer", "lastname", "last", "name", "value", "reed", "shippingaddress", "shipping" ], "diagram": { "actors": [ { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "Calls the Payroc API to find the secure token and patch its saved details." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." } ], "steps": [ { "title": "List secure tokens", "label": "token search", "badge": "REST · token search", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "listSecureTokens" }, { "title": "Get secure token", "label": "token lookup", "badge": "REST · token lookup", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "getSecureToken" }, { "title": "Update secure token", "label": "JSON Patch update", "badge": "REST · JSON Patch update", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "updateSecureToken" } ] } }, "update-an-event-subscription": { "workflowId": "update-an-event-subscription", "domain": "notifications", "title": "Fully replace an event subscription via PUT.", "summary": "Fully replace an event subscription via PUT.", "stepCount": 1, "gotchas": [ "PUT (updateEventSubscription) is a full replace and returns 204 No Content; re-run getEventSubscription (see create-and-manage-an-event-subscription) to confirm the new state.", "The subscriptionId is the int64 id returned by create at `#/id`." ], "operationIds": [ "updateEventSubscription" ], "workflowRefs": [], "keywords": [ "processingaccount", "processing", "account", "status", "changed", "https", "server", "notification", "endpoint", "abcd1234efgh5678ijkl9012mnop3456", "d1234e", "h5678i", "l9012m", "p3456", "jane", "doe" ], "diagram": { "actors": [ { "id": "integrator", "name": "Integrator", "type": "client", "description": "Replaces the subscription; the only API caller in this workflow." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." } ], "steps": [ { "title": "Update subscription", "label": "replace event subscription", "badge": "REST · replace event subscription", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "updateEventSubscription" } ] } }, "update-an-owner": { "workflowId": "update-an-owner", "domain": "boarding", "title": "List, retrieve, then update (full PUT) an owner.", "summary": "List, retrieve, then update (full PUT) an owner.", "stepCount": 3, "gotchas": [], "operationIds": [ "listMerchantOwners", "getOwner", "updateOwner" ], "workflowRefs": [], "keywords": [ "processingaccountid", "processing", "account", "ownerid", "limit", "create", "owners", "listowners", "getowner", "get", "updateowner", "funding", "recipient", "api", "content", "returned" ], "diagram": { "actors": [ { "id": "integrator", "name": "Integrator", "type": "client", "description": "Finds and updates the owner; the only API caller in this workflow." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." } ], "steps": [ { "title": "List owners", "label": "list owners", "badge": "REST · list owners", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "listMerchantOwners" }, { "title": "Get owner", "label": "get owner", "badge": "REST · get owner", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "getOwner" }, { "title": "Update owner", "label": "update owner", "badge": "REST · update owner", "actorId": "integrator", "actorToId": "payroc-gateway", "operationId": "updateOwner" } ] } }, "verify-a-bank-account": { "workflowId": "verify-a-bank-account", "domain": "payments", "title": "Verify a customer's ACH (or PAD) bank account details.", "summary": "Verify a customer's ACH (or PAD) bank account details.", "stepCount": 1, "gotchas": [], "operationIds": [ "verifyBankAccount" ], "workflowRefs": [], "keywords": [ "type", "accounttype", "checking", "nameonaccount", "name", "sarah", "hazel", "hopper", "accountnumber", "number", "routingnumber", "routing", "seccode", "sec", "code", "web" ], "diagram": { "actors": [ { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "Calls the Payroc API to verify the customer's bank account details before an ACH sale or funding setup." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." } ], "steps": [ { "title": "Verify bank account", "label": "bank verification request", "badge": "REST · bank verification request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "verifyBankAccount" } ] } }, "verify-a-card": { "workflowId": "verify-a-card", "domain": "payments", "title": "Verify a customer's card with a zero-value authorization.", "summary": "Verify a customer's card with a zero-value authorization.", "stepCount": 1, "gotchas": [], "operationIds": [ "verifyCard" ], "workflowRefs": [], "keywords": [ "jane", "sarah", "hazel", "hopper", "processingterminalid", "processing", "terminal", "idempotencykey", "idempotency", "key", "operator", "cardholdername", "cardholder", "name", "cardnumber", "number" ], "diagram": { "actors": [ { "id": "merchant", "name": "Merchant / integrator", "type": "client", "description": "Calls the Payroc API to verify the customer's card with a zero-value authorization." }, { "id": "payroc-gateway", "name": "Payroc gateway", "type": "api", "description": "The Payroc API surface these steps call." }, { "id": "processor", "name": "Payment processor", "type": "external-system", "description": "Downstream processor whose verification outcome is reported in transactionResult; not directly callable." } ], "steps": [ { "title": "Verify card", "label": "card verification request", "badge": "REST · card verification request", "actorId": "merchant", "actorToId": "payroc-gateway", "operationId": "verifyCard" } ] } } }, "domains": { "payments": 39, "attachments": 1, "boarding": 13, "payroc-cloud": 7, "notifications": 3, "funding": 10, "reporting": 1 }, "domainLabels": { "payments": "Payments", "attachments": "Attachments", "boarding": "Boarding", "payroc-cloud": "Payroc Cloud", "notifications": "Notifications", "funding": "Funding", "reporting": "Reporting" } }