{ "version": 1, "entries": [ { "route": "/api", "type": "guide", "title": "Introduction", "description": "Overview of the Payroc API, covering merchant boarding, funding accounts, transaction processing, and core features such as idempotency, metadata, pagination, and versioning.", "headings": [], "plainText": "Use our API explorer to view a detailed breakdown of our API and to discover how you can integrate with it to do the following: Board merchants - Add merchants to your organization and set up their accounts. Manage funding accounts - Move funds to your merchants and other organizations. Run transactions - Take payments from customers using a range of payment methods. Our API supports the following features: Idempotency Metadata Pagination Versioning We also provide easy-to-use guides that contain all the information you need to integrate with the key functions of our API.", "refs": { "workflowIds": [], "operationIds": [] } }, { "route": "/api/account-update", "type": "reference", "title": "Update account details", "description": "POST /processing-terminals/{processingTerminalId}/secure-tokens/{secureTokenId}/update-account", "headings": [], "plainText": "Use this method to update a secure token if you have a single-use token from Hosted Fields. Note: If you don't have a single-use token, you can update saved payment details with our Update Secure Token method. For more information about our two options to update a secure token, go to Update saved payment details .", "refs": { "workflowIds": [ "refresh-a-saved-payment-method" ], "operationIds": [ "accountUpdate" ] } }, { "route": "/api/adjust-payment", "type": "reference", "title": "Adjust payment", "description": "POST /payments/{paymentId}/adjust", "headings": [], "plainText": "Use this method to adjust a payment in an open batch. To adjust a payment, you need its paymentId. Our gateway returned the paymentId in the response of the Create Payment method. Note: If you don't have the paymentId, use our List Payments method to search for the payment. You can adjust the following details of the payment: Sale amount and tip amount Payment status Cardholder shipping address and contact information Cardholder signature data Our gateway returns information about the adjusted payment, including information about the payment card and the cardholder.", "refs": { "workflowIds": [ "adjust-a-payment", "run-a-pre-authorization" ], "operationIds": [ "adjustPayment" ] } }, { "route": "/api/adjust-refund", "type": "reference", "title": "Adjust refund", "description": "POST /refunds/{refundId}/adjust", "headings": [], "plainText": "Use this method to adjust a refund in an open batch. To adjust a refund, you need its refundId. Our gateway returned the refundId in the response of the Refund Payment method or the Create Refund method. Note: If you don’t have the refundId, use our List Refunds method to search for the refund. You can adjust the following details of the refund: Customer details, including shipping address and contact information. Status of the refund. Our gateway returns information about the adjusted refund, including: Order details, including the refund amount and when we processed the refund. Payment card details, including the masked card number, expiry date, and payment method. Cardholder details, including their contact information and shipping address. If the refund is a referenced refund, our gateway also returns details about the payment that the refund is linked to.", "refs": { "workflowIds": [ "adjust-a-refund" ], "operationIds": [ "adjustRefund" ] } }, { "route": "/api/apple-pay-sessions", "type": "reference", "title": "Start Apple Pay session", "description": "POST /processing-terminals/{processingTerminalId}/apple-pay-sessions", "headings": [], "plainText": "Use this method to start an Apple Pay session for your merchant. In the response, we return the startSessionObject that you send to Apple when you retrieve the cardholder's encrypted payment details. Note: For more information about how to integrate with Apple Pay, go to Apple Pay .", "refs": { "workflowIds": [ "accept-apple-pay" ], "operationIds": [ "applePaySessions" ] } }, { "route": "/api/authentication", "type": "guide", "title": "Authentication", "description": "How to authenticate Payroc API requests using API keys and Bearer tokens, including Identity Service endpoints, required request headers, and API key best practices.", "headings": [ "Request", "Example request", "Response", "Example response", "Request headers", "API key best practices" ], "plainText": "The Payroc API uses Bearer tokens to authenticate requests. Use our Identity Service to generate a Bearer token, and then send the token in the header of your requests to our API. Each Bearer token expires after one hour, and you must generate a new Bearer token before the previous one expires. Request Important: Use HTTPS for all requests to the Payroc API. We reject all HTTP requests, and all requests that are not properly authenticated. To generate a Bearer token, include your API key in the x-api-key parameter in the header of a POST request to the Identity Service endpoint. Note: API keys are specific to each environment, for example, you can't use your UAT API key with the Production endpoint. Endpoint Prefix URL Test identity.uat. https://identity.uat.payroc.com/authorize Production identity. https://identity.payroc.com/authorize Example request curl --location --request POST 'https://identity.payroc.com/authorize' --header 'x-api-key: ' Response If your request is successful, we generate a Bearer token and return it in the access_token field in the response. The response contains the following fields: Field Description access_token Bearer token that you include in follow-up requests to our API. expires_in Expiration time of the token in seconds. The value is 3600. scope Indicates the resources you can send requests to with the Bearer token. token_type Indicates the type of the token. Example response { \"access_token\": \"eyJhbGc....adQssw5c\", \"expires_in\": 3600, \"scope\": \"service_a service_b\", \"token_type\": \"Bearer\" } Request headers Include the following headers in each request to the Payroc API: Content-Type: Include application/json. Authorization: Include your Bearer token . Idempotency-Key: Include a UUID v4 to make POST and PATCH requests idempotent . curl -H \"Content-Type: application/json\" -H \"Authorization: Bearer \" -H \"Idempotency-Key: \" Note: Some endpoints require a different value for Content-Type. Check the individ", "refs": { "workflowIds": [], "operationIds": [] } }, { "route": "/api/balance-card", "type": "reference", "title": "View EBT balance", "description": "POST /cards/balance", "headings": [], "plainText": "Use this method to view the balance of an Electronic Benefit Transfer (EBT) card. If the request is successful, our gateway returns the current balance of an EBT card.", "refs": { "workflowIds": [ "check-ebt-balance" ], "operationIds": [ "balanceCard" ] } }, { "route": "/api/bank-transfer-payment", "type": "reference", "title": "Create payment", "description": "POST /bank-transfer-payments", "headings": [], "plainText": "Use this method to run a sale with a customer's bank account details. In the response, our gateway returns information about the bank transfer payment and a paymentId, which you need for the following methods: Retrieve payment - View the details of the bank transfer payment. Reverse payment - Cancel the bank transfer payment if it's an open batch. Refund payment - Run a referenced refund to return funds to the customer's bank account. Payment methods Our gateway accepts the following payment methods: Automated clearing house (ACH) details Pre-authorized debit (PAD) details You can also use secure tokens and single-use tokens that you created from ACH details or PAD details.", "refs": { "workflowIds": [ "run-a-bank-transfer-sale" ], "operationIds": [ "bankTransferPayment" ] } }, { "route": "/api/bank-transfer-unreferenced-refund", "type": "reference", "title": "Create unreferenced refund", "description": "POST /bank-transfer-refunds", "headings": [], "plainText": "Use this method to create an unreferenced refund. An unreferenced refund is a refund that isn’t linked to a bank transfer payment. Note: If you have the paymentId of the payment you want to refund, use our Refund Payment method. If you use our Refund Payment method, our gateway sends the refund amount to the customer’s original payment method and links the refund to the payment. In the request, you must provide the customer’s payment method and information about the order including the refund amount. In the response, our gateway returns information about the refund and a refundId, which you need for the following methods: Retrieve refund – View the details of the refund. Reverse refund – Cancel the refund if it’s in an open batch.", "refs": { "workflowIds": [ "run-unreferenced-bank-transfer-refund" ], "operationIds": [ "bankTransferUnreferencedRefund" ] } }, { "route": "/api/bin-lookup", "type": "reference", "title": "Look up BIN information", "description": "POST /cards/bin-lookup", "headings": [], "plainText": "Use this method to retrieve information about a debit card, a credit card, or an EBT card. If you apply surcharges to transactions, you can also check if the card supports surcharging. In the response, our gateway returns the following information about the card: Card details - Information about the card, for example, the issuing bank and the masked card number. Surcharging information - If you apply a surcharge to transactions, our gateway checks that the card supports surcharging and returns information about the surcharge. For more information about surcharging, go to Credit card surcharging .", "refs": { "workflowIds": [ "look-up-bin" ], "operationIds": [ "binLookup" ] } }, { "route": "/api/capture-payment", "type": "reference", "title": "Capture payment", "description": "POST /payments/{paymentId}/capture", "headings": [], "plainText": "Use this method to capture a pre-authorization. To capture a pre-authorization, you need its paymentId. Our gateway returned the paymentId in the response of the Create Payment method. Note: If you don't have the paymentId, use our List Payments method to search for the payment. Depending on the amount you want to capture, complete the following: Capture the full amount of the pre-authorization - Don't send a value for the amount parameter in your request. Capture less than the amount of the pre-authorization - Send a value for the amount parameter in your request. Capture more than the amount of the pre-authorization - Adjust the pre-authorization before you capture it. For more information about adjusting a pre-authorization, go to Adjust Payment . If your request is successful, our gateway takes the amount from the payment card. Note: For more information about pre-authorizations and captures, go to Run a pre-authorization .", "refs": { "workflowIds": [ "collect-with-hosted-payment-page", "run-a-pre-authorization" ], "operationIds": [ "capturePayment" ] } }, { "route": "/api/close-bank-transfer-payment", "type": "reference", "title": "Close return", "description": "POST /bank-transfer-payments/{paymentId}/close", "headings": [], "plainText": "Use this method to close a return if the customer used an alternative payment method to resolve a returned payment. To close a return, you need the paymentId of the return. To get the paymentId of the return, complete the following steps: Use our Retrieve Payment method to view the details of the original payment. From the returns object in the response, get the paymentId of the return. If your request is successful, our gateway closes the return.", "refs": { "workflowIds": [ "close-ach-return" ], "operationIds": [ "closeBankTransferPayment" ] } }, { "route": "/api/close-batch", "type": "reference", "title": "Close batch for processing terminal", "description": "POST /processing-terminals/{processingTerminalId}/close-batch", "headings": [], "plainText": "Use this method to manually close a batch on a processing terminal. Our gateway returns a cut-off time that indicates when our gateway closes the batch. Note: After our gateway closes the batch, the merchant can use the Self-Care Portal to view the details of the batch.", "refs": { "workflowIds": [ "close-a-terminal-batch" ], "operationIds": [ "closeBatch" ] } }, { "route": "/api/create-event-subscription", "type": "reference", "title": "Create event subscription", "description": "POST /event-subscriptions", "headings": [], "plainText": "Use this method to create an event subscription that we use to notify you when an event occurs, for example, when we change the status of a processing account. In the request, include the events that you want to subscribe to and the public endpoint that we send event notifications to. For a complete list of events that you can subscribe to, go to Events List . In the response, our gateway returns the id of the event subscription, which you can use to perform follow-on actions.", "refs": { "workflowIds": [ "create-event-subscription" ], "operationIds": [ "createEventSubscription" ] } }, { "route": "/api/create-fund-recipient-funding-account", "type": "reference", "title": "Create funding account", "description": "POST /funding-recipients/{recipientId}/funding-accounts", "headings": [], "plainText": "Use this method to create a funding account and add it to a funding recipient. To add a funding account to a funding recipient, you need the recipientId. Our gateway returned the recipientId in the response of the Create Funding Recipient method. Note: If you don't have the recipientId, use our List Funding Recipients method to search for the funding recipient. In the request, include the following information: Account type, for example, if the account is a checking or savings account. Account holder's name. ACH information, including the routing number and account number of the account. Our gateway returns the fundingAccountId, which you can use to run follow-on actions.", "refs": { "workflowIds": [ "set-up-a-funding-recipient" ], "operationIds": [ "createFundRecipientFundingAccount" ] } }, { "route": "/api/create-fund-recipient-owner", "type": "reference", "title": "Create funding recipient owner", "description": "POST /funding-recipients/{recipientId}/owners", "headings": [], "plainText": "Use this method to add an additional owner to a funding recipient. To add an owner to a funding recipient, you need the recipientId. Our gateway returned the recipientId in the response of the Create Funding Recipient method. Note: If you don't have the recipientId, use our List Funding Recipients method to search for the funding recipient. In the request, include the following information about the owner: Name, date of birth, and address. Contact details, including their email address. Relationship to the funding recipient, including whether they are a control prong. In the response, our gateway returns the ownerId, which you can use to run follow-on actions.", "refs": { "workflowIds": [ "set-up-a-funding-recipient" ], "operationIds": [ "createFundRecipientOwner" ] } }, { "route": "/api/create-funding-recipient", "type": "reference", "title": "Create funding recipient", "description": "POST /funding-recipients", "headings": [], "plainText": "Use this method to create a funding recipient. A funding recipient is a business or organization that can receive funds but can't run transactions, for example, a charity. In the request, include the following information: Legal information, including its tax ID, Doing Business As (DBA) name, and address. Contact information, including the email address. Owners' details, including their contact details. Funding account details. Our gateway returns the recipientId of the funding recipient, which you can use to run follow-on actions.", "refs": { "workflowIds": [ "set-up-a-funding-recipient" ], "operationIds": [ "createFundingRecipient" ] } }, { "route": "/api/create-instruction", "type": "reference", "title": "Create funding instruction", "description": "POST /funding-instructions", "headings": [], "plainText": "Use this method to create a funding instruction that tells us how to distribute the funds from your merchants' transactions. Note: Before you create a funding instruction, you can use our List Funding Balances method to view the amount of available funds that a merchant has. In your request, include an array of merchantInstruction objects. Each merchantInstruction object contains the following: Merchant ID (MID) of the merchant whose funding balance you want to distribute. Funding account that you want to send funds to. Amount that you want to send to the funding account. Our gateway returns the instructionId, which you can use to run follow-on actions.", "refs": { "workflowIds": [ "send-funds-to-a-merchant" ], "operationIds": [ "createInstruction" ] } }, { "route": "/api/create-merchant", "type": "reference", "title": "Create merchant platform", "description": "POST /merchant-platforms", "headings": [], "plainText": "Use this method to board a merchant with Payroc. Note : This method is part of our Boarding solution. To help you understand how this method works with other Boarding methods, go to Board a Merchant . In the request, include the following information: Legal information, including its legal name and address. Contact information, including the email address for the business. Processing account information, including the pricing model, owners, and contacts for the processing account. When you send a successful request, we review the merchant's information. After we complete our review and approve the merchant, we assign: merchantPlatformId - Unique identifier for the merchant platform. processingAccountId - Unique identifier for each processing account linked to the merchant platform. You need to keep these to perform follow-on actions, for example, you need the processingAccountId to order terminals for the processing account.", "refs": { "workflowIds": [ "create-merchant-platform" ], "operationIds": [ "createMerchant" ] } }, { "route": "/api/create-payment-link", "type": "reference", "title": "Create payment link", "description": "POST /processing-terminals/{processingTerminalId}/payment-links", "headings": [], "plainText": "Use this method to create a payment link that a customer can use to make a payment for goods or services. The request includes the following settings: type - Indicates whether the link can be used only once or if it can be used multiple times. authType - Indicates whether the transaction is a sale or a pre-authorization. paymentMethod - Indicates the payment methods that the merchant accepts. charge - Indicates whether the merchant or the customer enters the amount for the transaction. If your request is successful, our gateway returns a paymentLinkId, which you can use to perform follow-on actions. Note: To share the payment link with a customer, use our Share Payment Link method.", "refs": { "workflowIds": [ "collect-with-payment-link" ], "operationIds": [ "createPaymentLink" ] } }, { "route": "/api/create-payment-plan", "type": "reference", "title": "Create payment plan", "description": "POST /processing-terminals/{processingTerminalId}/payment-plans", "headings": [], "plainText": "Use this method to create a payment schedule that you can assign customers to. Note: This method is part of our Repeat Payments feature. To help you understand how this method works with our Subscriptions endpoints, go to Repeat Payments . When you create a payment plan you need to provide a unique paymentPlanId that you use to run follow-on actions: Retrieve Payment Plan - View the details of the payment plan. Update Payment Plan - Update the details of the payment plan. Delete Payment Plan - Delete the payment plan. Create Subscription - Subscribe a customer to the payment plan. The request includes the following settings: type - Indicates if our gateway or the merchant collects payments. If the merchant manually collects payments, integrate with the Pay Manual Subscription method. recurringOrder - Amount of each payment if the gateway automatically collect payments. setupOrder - Setup fee that our gateway immediately collects from the customer's payment method. onUpdate and onDelete - Indicates what happens to associated subscriptions if the merchant updates or deletes the payment plan.", "refs": { "workflowIds": [ "manage-payment-plans" ], "operationIds": [ "createPaymentPlan" ] } }, { "route": "/api/create-pricing-intent", "type": "reference", "title": "Create pricing intent", "description": "POST /pricing-intents", "headings": [], "plainText": "Use this method to create a pricing intent that you can assign to a processing account. In the request, you must provide the following: Processing fees, including the pricing program and the fee to process each transaction. Gateway fees, including the fee for each transaction handled by our gateway. Base fees, including maintenance and PCI fees. In the response, our gateway returns information about the pricing intent and the pricingIntentId, which you need for the following methods: Create Merchant Platform - Assign the pricing intent to a processing account, when you create the merchant platform and its processing accounts. Create Processing Account - Assign the pricing intent to a processing account. Retrieve Pricing Intent - Retrieve information about a pricing intent. Update Pricing Intent - Update the details of a pricing intent. Delete Pricing Intent - Delete a pricing intent. Partially Update Pricing Intent - Partially update the details of a pricing intent.", "refs": { "workflowIds": [ "create-pricing-intent", "manage-pricing-intents" ], "operationIds": [ "createPricingIntent" ] } }, { "route": "/api/create-processing-account", "type": "reference", "title": "Create processing account", "description": "POST /merchant-platforms/{merchantPlatformId}/processing-accounts", "headings": [], "plainText": "Use this method to add an additional processing account to a merchant platform. To add a processing account to a merchant platform, you need the merchantPlatformId. Our gateway returned the merchantPlatformId in the response of the Create Merchant Platform method. Note : If you don't have the merchantPlatformId, use our List Merchant Platforms method to search for the merchant platform. In the request, include the following information: Business details, including its business type, time zone, and address. Owners' details, including their contact details. Funding, pricing, and processing information, including its pricing model and funding accounts. Additional forms that you need us to send to the merchant, for example, attestations and questionnaires. When you send a successful request, we review the information about the processing account. After we complete our review and approve the processing account, we assign a processingAccountId, which you need to perform follow-on actions. Note : You can subscribe to our processingAccount.status.changed event to get notifications when we update the status of a processing account. For more information about how to subscribe to events, go to Events List .", "refs": { "workflowIds": [ "add-processing-account" ], "operationIds": [ "createProcessingAccount" ] } }, { "route": "/api/create-processing-account-attachment", "type": "reference", "title": "Upload attachment to processing account", "description": "POST /processing-accounts/{processingAccountId}/attachments", "headings": [], "plainText": "Before you upload an attachment, make sure that you follow local privacy regulations and get the merchant's consent to process their information. Note: You need the ID of the processing account before you can upload an attachment. If you don't know the processingAccountId, go to the Retrieve a Merchant Platform method. The attachment must be an uncompressed file under 50MB in one of the following formats: .bmp, csv, .doc, .docx, .gif, .htm, .html, .jpg, .jpeg, .msg, .pdf, .png, .ppt, .pptx, .tif, .tiff, .txt, .xls, .xlsx In the request, include the attachment that you want to upload and the following information about the attachment: type - Type of attachment that you want to upload. description - Short description of the attachment. In the response, our gateway returns information about the attachment including its upload status and an attachmentId that you can use to Retrieve the details of the Attachment .", "refs": { "workflowIds": [ "add-attachment" ], "operationIds": [ "createProcessingAccountAttachment" ] } }, { "route": "/api/create-reminder", "type": "reference", "title": "Create reminder for processing account", "description": "POST /processing-accounts/{processingAccountId}/reminders", "headings": [], "plainText": "Use this method to prompt a merchant to sign their pricing agreement. You can create a reminder only if you requested the merchant’s signature by email when you created the processing account for the merchant. To create a reminder, you need the processingAccountId. Our gateway returned the processingAccountId in the response of the Create Merchant Platform method or Create Processing Account method. Note: If you don’t know the processingAccountId, use our List Merchant Platform’s Processing Accounts method to search for the processing account. When you send a successful request, we send an email to the merchant that prompts them to sign their pricing agreement.", "refs": { "workflowIds": [ "add-processing-account", "create-merchant-platform" ], "operationIds": [ "createReminder" ] } }, { "route": "/api/create-secure-token", "type": "reference", "title": "Create secure token", "description": "POST /processing-terminals/{processingTerminalId}/secure-tokens", "headings": [], "plainText": "Use this method to create a secure token that represents a customer's payment details. When you create a secure token, you need to generate and provide a secureTokenId that you use to run follow-on actions: Retrieve Secure Token – View the details of the secure token. Delete Secure Token – Delete the secure token. Update Secure Token – Update the details of the secure token. Update Account Details – Update the secure token with the details from a single-use token. Note: If you don't generate a secureTokenId to identify the token, our gateway generates a unique identifier and returns it in the response. If the request is successful, our gateway returns a token that the merchant can use in transactions instead of the customer's sensitive payment details, for example, when they run a sale .", "refs": { "workflowIds": [ "save-a-card-with-hosted-fields", "save-a-payment-method" ], "operationIds": [ "createSecureToken" ] } }, { "route": "/api/create-session", "type": "reference", "title": "Create Hosted Fields session", "description": "POST /processing-terminals/{processingTerminalId}/hosted-fields-sessions", "headings": [], "plainText": "Use this method to create a Hosted Fields session token. You need to generate a new session token each time you load Hosted Fields on a webpage. In your request, you need to indicate whether the merchant is using Hosted Fields to run a sale, save payment details, or update saved payment details. In the response, our gateway returns the session token and the time that it expires. You need the session token when you configure the JavaScript for Hosted Fields. For more information about adding Hosted Fields to a webpage, go to Hosted Fields .", "refs": { "workflowIds": [ "collect-with-hosted-fields", "save-a-card-with-hosted-fields" ], "operationIds": [ "createSession" ] } }, { "route": "/api/create-single-use-token", "type": "reference", "title": "Create single use token", "description": "POST /processing-terminals/{processingTerminalId}/single-use-tokens", "headings": [], "plainText": "Use this method to create a single-use token that represents a customer’s payment details. A single-use token expires after 30 minutes and merchants can use them only once. Note: To create a reusable permanent token, go to Create Secure Token . In the request, send the customer’s payment details. If the request is successful, our gateway returns a token that you can use in a follow-on action, for example, run a sale .", "refs": { "workflowIds": [ "pay-with-single-use-token" ], "operationIds": [ "createSingleUseToken" ] } }, { "route": "/api/create-subscription", "type": "reference", "title": "Create subscription", "description": "POST /processing-terminals/{processingTerminalId}/subscriptions", "headings": [], "plainText": "Use this method to assign a customer to a payment plan. Note: This method is part of our Repeat Payments feature. To help you understand how this method works with our Payment plans endpoints, go to Repeat Payments . When you create a subscription you need to provide a unique subscriptionId that you use to run follow-on actions: Retrieve Subscription - View the details of the subscription. Update Subscription - Update the details of the subscription. Deactivate Subscription - Stop taking payments for the subscription. Re-activate Subscription - Start taking payments again for the subscription. Pay Manual Subscription - Manually collect a payment for the subscription. The request includes the following settings: paymentPlanId - Unique identifier of the payment plan that the merchant wants to use. If you don't have the paymentPlanId, use our List Payment Plans method to search for the payment plan. paymentMethod - Object that contains information about the secure token, which represents the customer's card details or bank account details. startDate - Date that you want to start to take payments. You can also update the settings that the subscription inherited from the payment plan, for example, you can change the amount for each payment. If you change the settings for the subscription, it doesn't change the settings in the payment plan that it's linked to.", "refs": { "workflowIds": [ "manage-subscriptions" ], "operationIds": [ "createSubscription" ] } }, { "route": "/api/create-terminal-order", "type": "reference", "title": "Create terminal order", "description": "POST /processing-accounts/{processingAccountId}/terminal-orders", "headings": [], "plainText": "Use this method to order and configure terminals for a processing account. Note : You need the ID of the processing account before you can create an order. If you don't know the processingAccountId, go to the Retrieve a Merchant Platform method. In the request, specify the gateway settings, device settings, and application settings for the terminal. In the response, our gateway returns information about the terminal order including its status and terminalOrderId that you can use to retrieve the terminal order . Note : You can subscribe to the terminalOrder.status.changed event to get notifications when we update the status of a terminal order. For more information about how to subscribe to events, go to Events Subscriptions .", "refs": { "workflowIds": [ "order-a-terminal" ], "operationIds": [ "createTerminalOrder" ] } }, { "route": "/api/deactivate-payment-link", "type": "reference", "title": "Deactivate payment link", "description": "POST /payment-links/{paymentLinkId}/deactivate", "headings": [], "plainText": "Use this method to deactivate a payment link. To deactivate a payment link, you need its paymentLinkId. Our gateway returned the paymentLinkId in the response of the Create Payment Link method. Note: If you don't have the paymentLinkId, use our List Payment Links method to search for the payment link. If your request is successful, our gateway deactivates the payment link. The customer can't use the link to make a payment, and you can't reactivate the payment link.", "refs": { "workflowIds": [ "collect-with-payment-link" ], "operationIds": [ "deactivatePaymentLink" ] } }, { "route": "/api/deactivate-subscription", "type": "reference", "title": "Deactivate subscription", "description": "POST /processing-terminals/{processingTerminalId}/subscriptions/{subscriptionId}/deactivate", "headings": [], "plainText": "Use this method to deactivate a subscription. To deactivate a subscription, you need its subscriptionId, which you sent in the request of the Create Subscription method. Note: If you don't have the subscriptionId, use our List Subscriptions method to search for the subscription. If your request is successful, our gateway stops taking payments from the customer. To reactivate the subscription, use our Reactivate Subscription method.", "refs": { "workflowIds": [ "deactivate-a-subscription" ], "operationIds": [ "deactivateSubscription" ] } }, { "route": "/api/delete-contact", "type": "reference", "title": "Delete contact", "description": "DELETE /contacts/{contactId}", "headings": [], "plainText": "Use this method to delete a contact associated with a processing account. To delete a contact, you need their contactId. Our gateway returned the contactId in the response of the Create Processing Account method. Note: If you don’t have the contactId, use our Retrieve Processing Account method or our List Contacts method to search for the contact.", "refs": { "workflowIds": [ "delete-a-contact" ], "operationIds": [ "deleteContact" ] } }, { "route": "/api/delete-event-subscription", "type": "reference", "title": "Delete event subscription", "description": "DELETE /event-subscriptions/{subscriptionId}", "headings": [], "plainText": "Use this method to delete an event subscription. Important: After you delete an event subscription, you can’t recover it. You won't receive event notifications from the event subscription. To delete an event subscription, you need its subscriptionId. Our gateway returned the subscriptionId in the response of the Create Event Subscription method. If you want to stop receiving event notifications but don't want to delete the event subscription, use our Update Event Subscription method to deactivate it.", "refs": { "workflowIds": [ "create-event-subscription" ], "operationIds": [ "deleteEventSubscription" ] } }, { "route": "/api/delete-funding-account", "type": "reference", "title": "Delete funding account", "description": "DELETE /funding-accounts/{fundingAccountId}", "headings": [], "plainText": "Important: You can't delete a funding account that is associated with a processing account. Use this method to delete a funding account that is associated with a funding recipient. To delete a funding account, you need its fundingAccountId. Our gateway returned the fundingAccountId when you created the funding account. Note: If you don't have the fundingAccountId, use our List Funding Accounts method to search for the funding account.", "refs": { "workflowIds": [ "delete-a-funding-account" ], "operationIds": [ "deleteFundingAccount" ] } }, { "route": "/api/delete-funding-recipient", "type": "reference", "title": "Delete funding recipient", "description": "DELETE /funding-recipients/{recipientId}", "headings": [], "plainText": "Use this method to delete a funding recipient, including its funding accounts and owners. To delete a funding recipient, you need its recipientId. Our gateway returned the recipientId in the response of the Create Funding Recipient method. Note : If you don't have the recipientId, use our List Funding Recipients method to search for the funding recipient.", "refs": { "workflowIds": [ "delete-a-funding-recipient" ], "operationIds": [ "deleteFundingRecipient" ] } }, { "route": "/api/delete-instructions", "type": "reference", "title": "Delete funding instruction", "description": "DELETE /funding-instructions/{instructionId}", "headings": [], "plainText": "Important: You can delete a funding instruction only if its status is accepted . To view the status of a funding instruction, use our Retrieve Funding Instruction method. Use this method to delete a funding instruction. To delete a funding instruction, you need its instructionId. Our gateway returned the instructionId in the response of the Create Funding Instruction method. Note: If you don't have the instructionId, use our List Funding Instructions method to search for the funding instruction.", "refs": { "workflowIds": [ "delete-a-funding-instruction" ], "operationIds": [ "deleteInstructions" ] } }, { "route": "/api/delete-owner", "type": "reference", "title": "Delete owner", "description": "DELETE /owners/{ownerId}", "headings": [], "plainText": "Important: You can't delete an owner of a processing account. Use this method to delete an owner associated with a funding recipient. You can delete an owner only if the funding recipient has more than one owner. To delete an owner, you need their ownerId. Our gateway returned the ownerId in the response of the Create Funding Recipient method and the Create Funding Recipient Owner method. Note: If you don't have the ownerId, use the List Funding Recipient Owners method, the Retrieve Funding Recipient method, or the List Funding Recipients method to search for the funding recipient owner.", "refs": { "workflowIds": [ "delete-an-owner" ], "operationIds": [ "deleteOwner" ] } }, { "route": "/api/delete-payment-instruction", "type": "reference", "title": "Cancel payment instruction", "description": "DELETE /payment-instructions/{paymentInstructionId}", "headings": [], "plainText": "Use this method to cancel a payment instruction. You can cancel a payment instruction only if its status is inProgress . To retrieve the status of a payment instruction, use our Retrieve Payment Instruction method. To cancel a payment instruction, you need its paymentInstructionId. Our gateway returned the paymentInstructionId in the response of the Submit Payment Instruction method.", "refs": { "workflowIds": [ "cancel-a-device-payment-instruction" ], "operationIds": [ "deletePaymentInstruction" ] } }, { "route": "/api/delete-payment-plan", "type": "reference", "title": "Delete payment plan", "description": "DELETE /processing-terminals/{processingTerminalId}/payment-plans/{paymentPlanId}", "headings": [], "plainText": "Use this method to delete a payment plan. Important: When you delete a payment plan, you can’t recover it. You also won’t be able to add subscriptions to the payment plan. To delete a payment plan, you need its paymentPlanId, which you sent in the request of the Create Payment Plan method. Note: If you don't have the paymentPlanId, use our List Payment Plans method to search for the payment plan. The value you sent for the onDelete parameter when you created the payment plan indicates what happens to associated subscriptions when you delete the plan: complete - Our gateway stops taking payments for the subscriptions associated with the payment plan. continue - Our gateway continues to take payments for the subscriptions associated with the payment plan. To stop a subscription for a canceled payment plan, go to the Deactivate Subscription method.", "refs": { "workflowIds": [ "delete-a-payment-plan" ], "operationIds": [ "deletePaymentPlan" ] } }, { "route": "/api/delete-pricing-intent", "type": "reference", "title": "Delete pricing intent", "description": "DELETE /pricing-intents/{pricingIntentId}", "headings": [], "plainText": "Use this method to delete a pricing intent. Important: When you delete a pricing intent, you can't recover it. You also won't be able to assign the pricing intent to a merchant's boarding application. To delete a pricing intent, you need its pricingIntentId. Our gateway returned the pricingIntentId in the response of the Create Pricing Intent method. Note: If you don't have the pricingIntentId, use our List Pricing Intents method to search for the pricing intent.", "refs": { "workflowIds": [ "manage-pricing-intents" ], "operationIds": [ "deletePricingIntent" ] } }, { "route": "/api/delete-refund-instruction", "type": "reference", "title": "Cancel refund instruction", "description": "DELETE /refund-instructions/{refundInstructionId}", "headings": [], "plainText": "Use this method to cancel a refund instruction. You can cancel a refund instruction only if its status is inProgress . To retrieve the status of a refund instruction, use our Retrieve Refund Instruction method. To cancel a refund instruction, you need its refundInstructionId. Our gateway returned the refundInstructionId in the response of the Submit Refund Instruction method.", "refs": { "workflowIds": [ "cancel-a-device-refund-instruction" ], "operationIds": [ "deleteRefundInstruction" ] } }, { "route": "/api/delete-secure-token", "type": "reference", "title": "Delete secure token", "description": "DELETE /processing-terminals/{processingTerminalId}/secure-tokens/{secureTokenId}", "headings": [], "plainText": "Use this method to delete a secure token and its related payment details from our vault. To delete a secure token, you need its secureTokenId, which you sent in the request of the Create Secure Token method. Note: If you don’t have the secureTokenId, use our List Secure Tokens method to search for the secure token. When you delete a secure token, you can’t recover it, and you can’t reuse its identifier for a new token.", "refs": { "workflowIds": [ "delete-a-saved-payment-method" ], "operationIds": [ "deleteSecureToken" ] } }, { "route": "/api/delete-signature-instruction", "type": "reference", "title": "Cancel signature instruction", "description": "DELETE /signature-instructions/{signatureInstructionId}", "headings": [], "plainText": "Use this method to cancel a signature instruction. To cancel a signature instruction, you need its signatureInstructionId. Our gateway returned the signatureInstructionId in the response of the Submit signature instruction method.", "refs": { "workflowIds": [ "cancel-a-device-signature-instruction" ], "operationIds": [ "deleteSignatureInstruction" ] } }, { "route": "/api/errors", "type": "guide", "title": "Errors", "description": "Reference for all RFC-7807 error codes returned by the Payroc API, including error structure, causes, and example responses for each error type.", "headings": [ "Errors", "API error", "Example code", "Bad request", "Example code", "Cannot be canceled", "Example code", "Cannot be modified", "Example code", "Capability not supported", "Example code", "Card type is not supported", "Example code", "Contract already signed", "Example code", "Currency is not supported", "Example code", "Daily Discount and RewardPayChoice conflict", "Example code", "Duplicate unique reference", "Forbidden", "Example code", "Funding accounts limit reached", "Example code", "Funding accounts restricted", "Example code", "Idempotency key in use", "Example code", "Idempotency key missing", "Example code", "Insufficient funds", "Example code", "Internal server error", "KYC check failed", "Example code", "Method not supported", "National ID in use", "Example code", "No control prong or authorized signatory", "Example code", "No pricing agreement exists for the processing account", "Example code", "Not acceptable", "Example code", "Not authorized", "Example code", "Not found", "Example code", "Not requested by email", "Example code", "Payload too large", "Example code", "Processing terminal was not accepted", "Example code", "Recipient amount value limit exceeded", "Example code", "Resource already exists", "Example code", "Search too broad", "Example code", "Tax ID in use", "Example code", "Too many control prongs", "Example code", "Unsupported media type", "Example code", "Volume limit has been reached", "Example code" ], "plainText": "To help you identify and fix any errors that you may encounter, our errors follow RFC-7807 standards. Our errors include the following fields: type - Link to our developer portal for more information about the error. title - Short description about the error. status - HTTP status code. detail - Longer description about the error. Depending on the type of error we may return additional fields. Errors API error We can’t process your request. We also return an errors array that contains a message field for each error. The message field provides more detail about the error. Example code { \"type\": \"https://docs.payroc.com/api/errors#api-error\", \"title\": \"Api error\", \"status\": 500, \"detail\": \"We are unable to process your request at this time\" \"errors\": [ { \"message\": \"Service offline\" } ] } Bad request Your request is missing a parameter, or a value is in the wrong format. To help you identify the parameter, we also return an errors array that contains the following fields for each incorrect parameter: parameter - Name of the parameter that contains the error. detail - Short description of the error. message - Longer description of the error. Example code { \"type\": \"https://docs.payroc.com/api/errors#bad-request\", \"title\": \"Bad request\", \"status\": 400, \"detail\": \"One or more validation errors occurred, see error section for more info\", \"errors\": [ { \"parameter\": \"start_time\", \"detail\": \"invalid date\", \"message\": \"Expected time, got \\\\\\\"\\\\\\\" for start_time\" } ] } Cannot be canceled You can't cancel the instruction because the instruction failed or the payment device completed the instruction. If the payment device completed the instruction, our gateway also returns a link to the resource. Example code Instruction failed { \"type\": \"https://docs.payroc.com/api/errors#cannot-be-canceled\", \"title\": \"Cannot be canceled\", \"status\": 409, \"detail\": \"You cannot cancel this resource in its current state\", \"errors\": [ { \"message\": \"Failed instruction cannot be canceled\", \"parameter\"", "refs": { "workflowIds": [], "operationIds": [ "getFundingBalance", "listFundingAccount" ] } }, { "route": "/api/get-ach-deposit", "type": "reference", "title": "Retrieve ACH deposit", "description": "GET /ach-deposits/{achDepositId}", "headings": [], "plainText": "Use this method to retrieve information about an ACH deposit that we paid to a merchant. Note: To retrieve an ACH deposit, you need its achDepositId. If you don't have the achDepositId, use our List ACH Deposits method to search for the ACH deposit. Our gateway returns the following information about the ACH deposit: Merchant that we sent the ACH deposit to. Total amount that we paid the merchant. Breakdown of sales, returns, and fees.", "refs": { "workflowIds": [ "review-settlement-reporting" ], "operationIds": [ "getAchDeposit" ] } }, { "route": "/api/get-ach-deposit-fees", "type": "reference", "title": "List ACH deposit fees", "description": "GET /ach-deposit-fees", "headings": [], "plainText": "Retrieve a list of ACH deposit fees. Important: You must provide a value for either the 'date' query parameter or the 'achDepositId' query parameter.", "refs": { "workflowIds": [ "review-settlement-reporting" ], "operationIds": [ "getAchDepositFees" ] } }, { "route": "/api/get-ach-deposits", "type": "reference", "title": "List ACH deposits", "description": "GET /ach-deposits", "headings": [], "plainText": "Use this method to return a paginated list of ACH deposits that we paid to your merchants. Note: If you want to view the details of a specific ACH deposit and you have its achDepositId, use our Retrieve ACH Deposit method. Use query parameters to filter the list of results that we return, for example, to search for ACH deposits that we paid to a specific merchant. Important: You must provide a value for the date query parameter. Our gateway returns the following information about each ACH deposit in the list: Merchant that we sent the ACH deposit to. Total amount that we paid the merchant. Breakdown of sales, returns, and fees.", "refs": { "workflowIds": [ "review-settlement-reporting" ], "operationIds": [ "getAchDeposits" ] } }, { "route": "/api/get-attachment", "type": "reference", "title": "Retrieve attachment", "description": "GET /attachments/{attachmentId}", "headings": [], "plainText": "Use this method to retrieve the details of an attachment. To retrieve the details of an attachment you need its attachmentId. Our gateway returned the attachmentId in the response of the Upload Attachment to Processing Account method. Our gateway returns information about the attachment, including its upload status and the entity that the attachment is linked to. Our gateway doesn't return the file that you uploaded.", "refs": { "workflowIds": [ "add-attachment" ], "operationIds": [ "getAttachment" ] } }, { "route": "/api/get-authorization", "type": "reference", "title": "Retrieve authorization", "description": "GET /authorizations/{authorizationId}", "headings": [], "plainText": "Use this method to retrieve information about an authorization. Note: To retrieve an authorization, you need its authorizationId. If you don't have the authorizationId, use our List Authorizations method to search for the authorization. Our gateway returns the following information about the authorization: Authorization response from the issuing bank. Amount that the issuing bank authorized. Merchant that ran the authorization. Details about the customer's card, the transaction, and the batch.", "refs": { "workflowIds": [ "review-settlement-reporting" ], "operationIds": [ "getAuthorization" ] } }, { "route": "/api/get-authorizations", "type": "reference", "title": "List authorizations", "description": "GET /authorizations", "headings": [], "plainText": "Use this method to retrieve a paginated list of authorizations. Use query parameters to filter the list of results that we return, for example, to search for authorizations linked to a specific merchant. Important: You must provide a value for either the date query parameter or the batchId query parameter. Our gateway returns the following information about each authorization in the list: Authorization response from the issuing bank. Amount that the issuing bank authorized. Merchant that ran the authorization. Details about the customer's card, the transaction, and the batch.", "refs": { "workflowIds": [ "review-settlement-reporting" ], "operationIds": [ "getAuthorizations" ] } }, { "route": "/api/get-bank-transfer-payment", "type": "reference", "title": "Retrieve payment", "description": "GET /bank-transfer-payments/{paymentId}", "headings": [], "plainText": "Use this method to retrieve information about a bank transfer payment. To retrieve a payment, you need its paymentId. Our gateway returned the paymentId in the response of the Create Payment method. Note: If you don’t have the paymentId, use our List Payments method to search for the payment. Our gateway returns the following information about the payment: Order details, including the transaction amount and when it was processed. Bank account details, including the customer’s name and account number. Customer’s details, including the customer’s phone number. Transaction details, including any refunds or re-presentments. If the merchant saved the customer’s bank account details, our gateway returns a secureTokenID, which you can use to perform follow-on actions.", "refs": { "workflowIds": [ "close-ach-return", "refund-a-bank-transfer-payment", "represent-ach-payment" ], "operationIds": [ "getBankTransferPayment" ] } }, { "route": "/api/get-bank-transfer-refund", "type": "reference", "title": "Retrieve refund", "description": "GET /bank-transfer-refunds/{refundId}", "headings": [], "plainText": "Use this method to retrieve information about a refund. To retrieve a refund, you need its refundId. Our gateway returned the refundId in the response of the Refund Payment method or the Create Refund method. Note: If you don’t have the refundId, use our List Refunds method to search for the refund. Our gateway returns the following information about the refund: Order details, including the refund amount and when it was processed. Bank account details, including the customer’s name and account number. If the refund is a referenced refund, our gateway also returns details about the payment that the refund is linked to.", "refs": { "workflowIds": [ "reverse-a-bank-transfer-refund" ], "operationIds": [ "getBankTransferRefund" ] } }, { "route": "/api/get-closed-loop", "type": "reference", "title": "Retrieve closed loop read", "description": "GET /closed-loop-reads/{closedLoopReadId}", "headings": [], "plainText": "Use this method to retrieve information that a payment device captured from a closed-loop card. A closed-loop card is a type of card that a customer can use only with a specific merchant. Each time a payment device captures information from a closed-loop card, we store the information as a closed-loop read. Our gateway returns the following information from a closed-loop read: Date that the payment device captured the information. Unstructured payload from the card.", "refs": { "workflowIds": [], "operationIds": [ "getClosedLoop" ] } }, { "route": "/api/get-contact", "type": "reference", "title": "Retrieve contact", "description": "GET /contacts/{contactId}", "headings": [], "plainText": "Use this method to retrieve details about a contact. To retrieve a contact, you need its contactId. Our gateway returned the contactId in the Create Processing Account method. Note: If you don't have the contactId, use the List Contacts method to search for the contact. Our gateway returns the following information about a contact: Name and contact method, including their phone number or mobile number. Role within the business, for example, if they are a manager.", "refs": { "workflowIds": [ "delete-a-contact", "update-a-contact" ], "operationIds": [ "getContact" ] } }, { "route": "/api/get-event-subscription", "type": "reference", "title": "Retrieve event subscription", "description": "GET /event-subscriptions/{subscriptionId}", "headings": [], "plainText": "Use this method to retrieve the details of an event subscription. In your request, include the subscriptionId that we sent to you when we created the event subscription. Note: If you don't know the subscriptionId of the event subscription, go to List event subscriptions .", "refs": { "workflowIds": [ "create-event-subscription" ], "operationIds": [ "getEventSubscription" ] } }, { "route": "/api/get-funding-account", "type": "reference", "title": "Retrieve funding account", "description": "GET /funding-accounts/{fundingAccountId}", "headings": [], "plainText": "Use this method to retrieve information about a funding account. To retrieve a funding account, you need its fundingAccountId. Our gateway returned the fundingAccountId when you created the funding account. Note: If you don't have the fundingAccountId, use our List Funding Accounts method to search for the account. Our gateway returns the following information about the funding account: Name of the account holder and ACH details for the account. Status of the account. Whether we send funds to the account, withdraw funds from the account, or both.", "refs": { "workflowIds": [ "delete-a-funding-account", "update-a-funding-account" ], "operationIds": [ "getFundingAccount" ] } }, { "route": "/api/get-funding-activity", "type": "reference", "title": "List funding activity", "description": "GET /funding-activity", "headings": [], "plainText": "Use this method to return a paginated list of activity associated with your merchants' funding balances within a specific date range. Use query parameters to filter the list of results we return, for example, to view the activity for a specific merchant's funding balance. Our gateway returns the following information about each activity in the list: Name of the merchant who owns the funding balance. Amount of funds added or removed from the funding balance. Funding account that received funds from the funding balance.", "refs": { "workflowIds": [ "review-funding-activity" ], "operationIds": [ "getFundingActivity" ] } }, { "route": "/api/get-funding-balance", "type": "reference", "title": "List funding balances", "description": "GET /funding-balance", "headings": [], "plainText": "Use this method to return a paginated list of funding balances available for each merchant linked to your account. Use query parameters to filter the list of results we return, for example, to search for the funding balance for a specific merchant. Our gateway returns the following information about each merchant in the list: Total funds for the merchant. Available funds that you can use for funding instructions. Pending funds that we have not yet sent to funding accounts.", "refs": { "workflowIds": [ "review-funding-activity", "send-funds-to-a-merchant" ], "operationIds": [ "getFundingBalance" ] } }, { "route": "/api/get-funding-recipient", "type": "reference", "title": "Retrieve funding recipient", "description": "GET /funding-recipients/{recipientId}", "headings": [], "plainText": "Use this method to retrieve information about a funding recipient. To retrieve a funding recipient, you need its recipientId. Our gateway returned the recipientId in the response of the Create Funding Recipient method. Note: If you don't have the recipientId, use our List Funding Recipients method to search for the funding recipient. Our gateway returns the following information about the funding recipient: Tax ID and Doing Business As (DBA) name. Address and contact details. Funding accounts linked to the funding recipient.", "refs": { "workflowIds": [ "delete-a-funding-recipient", "manage-funding-recipients", "update-a-funding-recipient" ], "operationIds": [ "getFundingRecipient" ] } }, { "route": "/api/get-fx-rates", "type": "reference", "title": "Verify DCC eligibility", "description": "POST /fx-rates", "headings": [], "plainText": "Important: There are restrictions on which merchants can use this method. For more information, go to Dynamic Currency Conversion . Use this method to check if a card is eligible for Dynamic Currency Conversion (DCC) and to retrieve the conversion rate for a transaction amount. DCC provides a customer with the option to use their card's currency instead of the merchant's currency, for example, in Ireland, an American customer can pay in US dollars instead of Euros. The request includes the following: Payment method - Card information, a secure token, or digital wallet. Transaction information - Amount and currency of the transaction in the merchant's currency. If the card is eligible for DCC, our gateway returns the transaction amount in the card's currency and a dccOffer object that contains information about the conversion rate. The dccOffer object contains the following fields that you need when you run a sale or unreferenced refund with DCC: fxAmount fxCurrency fxRate markup accepted offerReference", "refs": { "workflowIds": [ "check-dcc-eligibility" ], "operationIds": [ "getFxRates" ] } }, { "route": "/api/get-instruction", "type": "reference", "title": "Retrieve funding instruction", "description": "GET /funding-instructions/{instructionId}", "headings": [], "plainText": "Use this method to retrieve information about a funding instruction. To retrieve a funding instruction, you need its instructionId. Our gateway returned the instructionId in the response of the Create Funding Instruction method. Note: If you don't have the instructionId, use our List Funding Instructions method to search for the funding instruction. Our gateway returns the following information about the funding instruction: Status of the funding instruction. Funding information, including which merchant's funding balance we distribute and the funding account that we send the balance to.", "refs": { "workflowIds": [ "delete-a-funding-instruction", "update-a-funding-instruction" ], "operationIds": [ "getInstruction" ] } }, { "route": "/api/get-merchant-accounts", "type": "reference", "title": "Retrieve merchant platform", "description": "GET /merchant-platforms/{merchantPlatformId}", "headings": [], "plainText": "Use this method to retrieve information about a merchant platform. To retrieve a merchant platform, you need its merchantPlatformId. Our gateway returned the merchantPlatformId in the response of the Create Merchant Platform method. Note: If you don't have the merchantPlatformId, use our List Merchant Platforms method to search for the merchant platform. Our gateway returns the following information about the merchant platform: Legal information, including its legal name and address. Contact information, including the email address for the business. Processing account information, including the processingAccountId and status of each processing account that's linked to the merchant platform.", "refs": { "workflowIds": [ "review-merchant-hierarchy" ], "operationIds": [ "getMerchantAccounts" ] } }, { "route": "/api/get-owner", "type": "reference", "title": "Retrieve owner", "description": "GET /owners/{ownerId}", "headings": [], "plainText": "Use this method to retrieve details about an owner of a processing account or an owner associated with a funding recipient. To retrieve an owner, you need their ownerId. Our gateway returned the ownerId in the response of the Create Processing Account method or the Create Funding Recipient Owner method. Note: If you don't have the ownerId, use the Retrieve Processing Account method if you are searching for a processing account owner, or use the List Funding Recipient Owners method if you are searching for a funding recipient owner. Our gateway returns the following information about an owner: Name, date of birth, and address. Contact details, including their email address. Relationship to the business, including whether they are a control prong or authorized signatory, and their equity stake in the business.", "refs": { "workflowIds": [ "delete-an-owner", "update-an-owner" ], "operationIds": [ "getOwner" ] } }, { "route": "/api/get-payment", "type": "reference", "title": "Retrieve payment", "description": "GET /payments/{paymentId}", "headings": [], "plainText": "Use this method to retrieve information about a card payment. To retrieve a payment, you need its paymentId. Our gateway returned the paymentId in the response of the Create Payment method. Note: If you don't have the paymentId, use our List Payments method to search for the payment. Our gateway returns the following information about the payment: Order details, including the transaction amount and when it was processed. Payment card details, including the masked card number, expiry date, and payment method. Cardholder details, including their contact information and shipping address. Payment details, including the payment type, status, and response. If the merchant saved the customer's card details, our gateway returns a secureTokenID, which you can use to perform follow-on actions.", "refs": { "workflowIds": [ "adjust-a-payment", "refund-a-card-payment", "run-a-sale-on-a-device" ], "operationIds": [ "getPayment" ] } }, { "route": "/api/get-payment-instruction", "type": "reference", "title": "Retrieve payment instruction", "description": "GET /payment-instructions/{paymentInstructionId}", "headings": [], "plainText": "Use this method to retrieve information about a payment instruction. To retrieve a payment instruction, you need its paymentInstructionId. Our gateway returned the paymentInstructionId in the response of the Submit Payment Instruction method. Our gateway returns the status of the payment instruction. If the payment device completed the payment instruction, the response also includes a link to the payment.", "refs": { "workflowIds": [ "cancel-a-device-payment-instruction", "run-a-sale-on-a-device" ], "operationIds": [ "getPaymentInstruction" ] } }, { "route": "/api/get-payment-intent", "type": "reference", "title": "Retrieve payment intent", "description": "GET /payment-intents/{paymentIntentId}", "headings": [], "plainText": "Use this method to retrieve a payment intent, including who is paying for the terminal order and how they are paying for the terminal order. Include the paymentIntentId that we sent you when you created the terminal order.", "refs": { "workflowIds": [], "operationIds": [ "getPaymentIntent" ] } }, { "route": "/api/get-payment-plan", "type": "reference", "title": "Retrieve payment plan", "description": "GET /processing-terminals/{processingTerminalId}/payment-plans/{paymentPlanId}", "headings": [], "plainText": "Use this method to retrieve information about a payment plan. To retrieve a payment plan, you need its paymentPlanId. Our gateway returned the paymentPlanId in the response of the Create Payment Plan method. Note: If you don't have the paymentPlanId, use our List Payment Plans method to search for the payment plan. Our gateway returns the following information about the payment plan: Name, length, and currency of the plan How often our gateway collects each payment How much our gateway collects for each payment What happens if the merchant updates or deletes the plan", "refs": { "workflowIds": [ "delete-a-payment-plan", "manage-payment-plans", "update-a-payment-plan" ], "operationIds": [ "getPaymentPlan" ] } }, { "route": "/api/get-pricing-intent", "type": "reference", "title": "Retrieve pricing intent", "description": "GET /pricing-intents/{pricingIntentId}", "headings": [], "plainText": "Use this method to retrieve information about a pricing intent. To retrieve a pricing intent, you need its pricingIntentId. Our gateway returned the pricingIntentId in the response of the Create Pricing Intent method. Note: If you don't have the pricingIntentId, use our List Pricing Intents method to search for the pricing intent. Our gateway returns the following information about the pricing intent: Information about the fees, including the base fees, gateway fees, and processor fees. Status of the pricing intent, including whether we approved the pricing intent.", "refs": { "workflowIds": [ "manage-pricing-intents" ], "operationIds": [ "getPricingIntent" ] } }, { "route": "/api/get-processing-accounts", "type": "reference", "title": "Retrieve processing account", "description": "GET /processing-accounts/{processingAccountId}", "headings": [], "plainText": "Use this method to retrieve information about a specific processing account. To retrieve a processing account, you need its processingAccountId. Our gateway returned the processingAccountId in the response of the Create Merchant Platform method or the Create Processing Account method. Note: If you don't have the processingAccountId, use our List Merchant Platform's Processing Accounts method to search for the processing account. Our gateway returns the following information about the processing account: Business information, including the Merchant Category Code (MCC), status of the processing account, and address of the business. Processing information, including the merchant’s refund policies and card types that the merchant accepts. Funding information, including funding schedules, funding fees, and details for the merchant’s funding accounts. Pricing information, including HATEOAS links to retrieve the pricing program for the processing account.", "refs": { "workflowIds": [ "review-merchant-hierarchy" ], "operationIds": [ "getProcessingAccounts" ] } }, { "route": "/api/get-processing-terminal", "type": "reference", "title": "Retrieve processing terminal", "description": "GET /processing-terminals/{processingTerminalId}", "headings": [], "plainText": "Important: You can retrieve a processing terminal only if the terminal order was created using the Payroc API. Use this method to retrieve information about a processing terminal. To retrieve a processing terminal, you need its processingTerminalId. Our gateway returned the processingTerminalId in the response of the Create Terminal Order method. Note: If you don't have the processingTerminalId, use our Retrieve Terminal Order method or our List Processing Terminals method to search for the processing terminal. Our gateway returns the following information about the processing terminal: Status indicating whether the terminal is active or inactive. Configuration settings, including gateway settings and application settings. Features, receipt settings, and security settings. Devices that use the processing terminal's configuration.", "refs": { "workflowIds": [ "configure-a-device" ], "operationIds": [ "getProcessingTerminal" ] } }, { "route": "/api/get-processing-terminal-host-configuration", "type": "reference", "title": "Retrieve host processor configuration", "description": "GET /processing-terminals/{processingTerminalId}/host-configurations", "headings": [], "plainText": "Use this method to retrieve the host processor configuration of a processing terminal. Integrate with this method only if you use your own gateway and want to validate the processor configuration. Our gateway returns the configuration settings for the merchant and the payment terminal.", "refs": { "workflowIds": [ "configure-a-device" ], "operationIds": [ "getProcessingTerminalHostConfiguration" ] } }, { "route": "/api/get-refund", "type": "reference", "title": "Retrieve refund", "description": "GET /refunds/{refundId}", "headings": [], "plainText": "Use this method to retrieve information about a refund. To retrieve a refund, you need its refundId. Our gateway returned the refundId in the response of the Refund Payment method or the Create Refund method. Note: If you don't have the refundId, use our List Refunds method to search for the refund. Our gateway returns the following information about the refund: Order details, including the refund amount and when we processed the refund. Payment card details, including the masked card number, expiry date, and payment method. Cardholder details, including their contact information and shipping address. If the refund is a referenced refund, our gateway also returns details about the payment that the refund is linked to.", "refs": { "workflowIds": [ "adjust-a-refund", "refund-on-a-device", "reverse-a-refund" ], "operationIds": [ "getRefund" ] } }, { "route": "/api/get-refund-instruction", "type": "reference", "title": "Retrieve refund instruction", "description": "GET /refund-instructions/{refundInstructionId}", "headings": [], "plainText": "Use this method to retrieve information about a refund instruction. To retrieve a refund instruction, you need its refundInstructionId. Our gateway returned the refundInstructionId in the response of the Submit Refund Instruction method. Our gateway returns the status of the refund instruction. If the payment device completed the refund instruction, the response also includes a link to the refund.", "refs": { "workflowIds": [ "cancel-a-device-refund-instruction", "refund-on-a-device" ], "operationIds": [ "getRefundInstruction" ] } }, { "route": "/api/get-secure-token", "type": "reference", "title": "Retrieve secure token", "description": "GET /processing-terminals/{processingTerminalId}/secure-tokens/{secureTokenId}", "headings": [], "plainText": "Use this method to retrieve information about a secure token. To retrieve a secure token, you need its secureTokenID, which you sent in the request of the Create Secure Token method. Note: If you don't have the secureTokenId, use our List Secure Tokens method to search for the secure token. Our gateway returns the following information about the secure token: Payment details that the secure token represents. Customer details, including shipping and billing addresses. Secure token that you can use to carry out transactions.", "refs": { "workflowIds": [ "delete-a-saved-payment-method", "refresh-a-saved-payment-method", "update-a-saved-payment-method" ], "operationIds": [ "getSecureToken" ] } }, { "route": "/api/get-signature-instruction", "type": "reference", "title": "Retrieve signature instruction", "description": "GET /signature-instructions/{signatureInstructionId}", "headings": [], "plainText": "Use this method to retrieve information about a signature instruction. To retrieve a signature instruction, you need its signatureInstructionId. Our gateway returned the signatureInstructionId in the response of the Submit Signature Instruction method. Our gateway returns the status of the instruction. If the payment device completed the instruction, the response also includes a link to retrieve the signature.", "refs": { "workflowIds": [ "cancel-a-device-signature-instruction", "capture-signature-on-a-device" ], "operationIds": [ "getSignatureInstruction" ] } }, { "route": "/api/get-subscription", "type": "reference", "title": "Retrieve subscription", "description": "GET /processing-terminals/{processingTerminalId}/subscriptions/{subscriptionId}", "headings": [], "plainText": "Use this method to retrieve information about a subscription. To retrieve a subscription, you need its subscriptionId. You sent the subscriptionId in the request of the Create subscription method. Note: If you don't have the subscriptionId, use our List subscriptions method to search for the subscription. Our gateway returns information about the following for the subscription: Payment plan the subscription is linked to. Secure token that represents cardholder’s payment details. Current state of the subscription, including its status, next due date, and invoices. Fees for setup and the cost of the recurring order. Subscription length, end date, and frequency. We also return the paymentPlanId and the secureTokenId, which you can use to perform follow-on actions.", "refs": { "workflowIds": [ "manage-subscriptions" ], "operationIds": [ "getSubscription" ] } }, { "route": "/api/get-terminal-order", "type": "reference", "title": "Retrieve terminal order", "description": "GET /terminal-orders/{terminalOrderId}", "headings": [], "plainText": "Use this method to retrieve information about a terminal order. To retrieve a terminal order, you need it's terminalOrderId. Our gateway returned the terminalOrderId in the response of the Create Terminal Order method. Note : If you don't have the terminalOrderId, use our List Terminal Orders method to search for the terminal order. Our gateway returns the following information about the terminal order: Status of the order Items in the order Training provider Shipping information Note : You can subscribe to our terminalOrder.status.changed event to get notifications when we update the status of a terminal order. For more information about how to subscribe to events, go to Events Subscriptions .", "refs": { "workflowIds": [ "order-a-terminal" ], "operationIds": [ "getTerminalOrder" ] } }, { "route": "/api/get-transactions", "type": "reference", "title": "List transactions", "description": "GET /transactions", "headings": [], "plainText": "Use this method to return a paginated list of your merchants’ transactions. Note: If you want to view the details of a specific transaction and you have its transactionId, use our Retrieve Transaction method. Use query parameters to filter the list of results that we return, for example, to search for transactions for a specific merchant. Important: You must provide a value for either the date query parameter or the batchId query parameter. Our gateway returns the following information about each transaction in the list: Merchant and processing account that ran the transaction. Transaction type, date, amount, and the payment method that the customer used. Batch that contains the transaction, and authorization details for the transaction. Processor that settled the transaction and the ACH deposit containing the transaction.", "refs": { "workflowIds": [ "review-settlement-reporting" ], "operationIds": [ "getTransactions" ] } }, { "route": "/api/getbatch", "type": "reference", "title": "Retrieve batch", "description": "GET /batches/{batchId}", "headings": [], "plainText": "Use this method to retrieve information about a batch. Note: To retrieve a batch, you need its batchId. If you don't have the batchId, use our List Batches method to search for the batch. Our gateway returns the following information about the batch: Transaction information, including the number of transactions and total value of sales. Merchant information, including the merchant ID (MID) and the processing account that the batch is associated with.", "refs": { "workflowIds": [ "review-settlement-reporting" ], "operationIds": [ "getbatch" ] } }, { "route": "/api/getbatches", "type": "reference", "title": "List batches", "description": "GET /batches", "headings": [], "plainText": "Use this method to return a paginated list of batches that your merchants submitted to the processor on a specific date. Note: If you want to view the details of a specific batch and you have its batchId, use our Retrieve Batch method. Use query parameters to filter the list of results that we return, for example, to search for batches that were submitted by a specific merchant. Important: You must provide a value for the date query parameter. Our gateway returns the following information about each batch in the list: Transaction information, including the number of transactions and total value of sales. Merchant information, including the merchant ID (MID) and the processing account that the batch is associated with.", "refs": { "workflowIds": [ "review-settlement-reporting" ], "operationIds": [ "getbatches" ] } }, { "route": "/api/getdisputes", "type": "reference", "title": "List disputes", "description": "GET /disputes", "headings": [], "plainText": "Use this method to return a paginated list of disputes. Use query parameters to filter the list of results that we return, for example, to search for disputes linked to a specific merchant. Important: You must provide a value for the date query parameter. Our gateway returns the following information about each dispute in the list: Its status, type, and description. Transaction that the dispute is linked to, including the transaction date, merchant who ran the transaction, and the payment method that the cardholder used.", "refs": { "workflowIds": [ "review-settlement-reporting" ], "operationIds": [ "getdisputes" ] } }, { "route": "/api/getdisputes-statuses", "type": "reference", "title": "List dispute statuses", "description": "GET /disputes/{disputeId}/statuses", "headings": [], "plainText": "Use this method to return the status history of a dispute. To view the status history of a dispute, you need its disputeId. If you don't have the disputeId, use our List Disputes method to search for the dispute. Our gateway returns a list that contains each status change, the date it was changed, and its updated status.", "refs": { "workflowIds": [ "review-settlement-reporting" ], "operationIds": [ "getdisputesStatuses" ] } }, { "route": "/api/gettransaction", "type": "reference", "title": "Retrieve transaction", "description": "GET /transactions/{transactionId}", "headings": [], "plainText": "Use this method to retrieve information about a transaction. Note: To retrieve a transaction, you need its transactionId. If you don't have the transactionId, use our List Transactions method to search for the transaction. Our gateway returns the following information about the transaction: Merchant and processing account that ran the transaction. Transaction type, date, amount, and the payment method that the customer used. Batch that contains the transaction, and authorization details for the transaction. Processor that settled the transaction and the ACH deposit containing the transaction.", "refs": { "workflowIds": [ "review-settlement-reporting" ], "operationIds": [ "gettransaction" ] } }, { "route": "/api/idempotency", "type": "guide", "title": "Idempotency", "description": "Explains how the Payroc API implements idempotency for POST and PATCH requests using the Idempotency-Key header to prevent duplicate processing.", "headings": [ "Example use case for idempotency", "How to make POST requests and PATCH requests idempotent", "How we process POST requests and PATCH requests" ], "plainText": "Idempotency is an important property of our API that prevents you from changing a record if you make the same request multiple times. If you send the same request, we return the same response that we returned for the initial request. We do not update the record. Example use case for idempotency You send a request to take a payment of $20 from a customer's account. Our gateway successfully processes the payment and takes $20 from the account. Our gateway sends you a response to notify you of the successful transaction. There is a network error, and the response doesn't reach you. You resend the request to process the payment. Our gateway detects that the request is the same as the initial request and resends the initial response. Our gateway does not process an additional $20 payment. We follow RESTful standards when designing our API, which means that all GET requests, PUT requests, and DELETE requests are idempotent. We have also implemented additional features to guarantee that POST requests and PATCH requests are idempotent. How to make POST requests and PATCH requests idempotent To implement idempotency on POST requests and PATCH requests, you must include an Idempotency-Key header with each request. If your request does not include an Idempotency-Key header, we return a 400 Bad Request error. Important: The value that you generate for an Idempotency-Key header must be a unique universal identifier version 4 (UUID v4) value. To support idempotent POST requests and PATCH requests, we save the following information for seven days: The Idempotency-Key value, URI, and body of your initial request The response body and status code that we returned for your initial request How we process POST requests and PATCH requests When we receive a POST request or PATCH request, we verify that it is unique by checking the combination of Idempotency-Key value, URI, and request body. Depending on the results of our verification, we complete one of the following actions: We have no", "refs": { "workflowIds": [], "operationIds": [] } }, { "route": "/api/list-bank-transfer-payments", "type": "reference", "title": "List payments", "description": "GET /bank-transfer-payments", "headings": [], "plainText": "Use this method to return a paginated list of payments. Note: If you want to view the details of a specific payment and you have its paymentId, use our Retrieve Payment method. Use query parameters to filter the list of results that we return, for example, to search for payments for a customer, a date range, or a settlement state. Our gateway returns the following information about each payment in the list: Order details, including the transaction amount and when it was processed. Bank account details, including the customer’s name and account number. Customer's details, including the customer’s phone number. Transaction details, including any refunds or re-presentments. For each transaction, we also return the paymentId and an optional secureTokenId, which you can use to perform follow-on actions.", "refs": { "workflowIds": [ "refund-a-bank-transfer-payment", "reverse-a-bank-transfer-payment" ], "operationIds": [ "listBankTransferPayments" ] } }, { "route": "/api/list-bank-transfer-refunds", "type": "reference", "title": "List refunds", "description": "GET /bank-transfer-refunds", "headings": [], "plainText": "Use this method to return a paginated list of bank transfer refunds. Note: If you want to view the details of a specific refund and you have its refundId, use our Retrieve Refund method. Use query parameters to filter the list of results that we return, for example, to search for refunds for a customer, an orderId, or a date range. Our gateway returns the following information about each refund in the list: Order details, including the refund amount and when it was processed. Bank account details, including the customer’s name and account number. For referenced refunds, our gateway also returns details about the payment that the refund is linked to.", "refs": { "workflowIds": [ "reverse-a-bank-transfer-refund" ], "operationIds": [ "listBankTransferRefunds" ] } }, { "route": "/api/list-event-subscriptions", "type": "reference", "title": "List event subscriptions", "description": "GET /event-subscriptions", "headings": [], "plainText": "Use this method to return a paginated list of event subscriptions that are linked to your ISV account. Note: If you want to view the details of a specific event subscription and you have its id, use our Retrieve Event Subscription method. Use query parameters to filter the list of results that we return, for example, to search for subscriptions with a specific status or an event type. Our gateway returns the following information about each subscription in the list: Event types that you have subscribed to. Whether you have enabled notifications for the subscription. How we contact you when an event occurs, including the endpoint that send notifications to. If there are any issues when we try to send you a notification, for example, if we can't contact your endpoint. For each event subscription, we also return its id, which you can use to perform follow-on actions.", "refs": { "workflowIds": [ "create-event-subscription" ], "operationIds": [ "listEventSubscriptions" ] } }, { "route": "/api/list-fund-recipient-funding-accounts", "type": "reference", "title": "List funding recipient's funding accounts", "description": "GET /funding-recipients/{recipientId}/funding-accounts", "headings": [], "plainText": "Use this method to return a list of funding accounts associated with a funding recipient. Note: If you want to view the details of a specific funding account and you have its fundingAccountId, use our Retrieve Funding Account method. To retrieve the funding accounts associated with a funding recipient, you need the recipientId. If you don't have the recipientId, use our List Funding Recipients method to search for the funding recipient. Our gateway returns the following information about each funding account: Name of the account holder. ACH details for the account. Status of the account. Our gateway also returns the fundingAccountId, which you can use to run follow-on actions.", "refs": { "workflowIds": [ "manage-funding-recipients" ], "operationIds": [ "listFundRecipientFundingAccounts" ] } }, { "route": "/api/list-fund-recipient-owners", "type": "reference", "title": "List funding recipient owners", "description": "GET /funding-recipients/{recipientId}/owners", "headings": [], "plainText": "Use this method to return a list of owners of a funding recipient. Note: If you want to view the details of a specific owner and you have their ownerId, use our Retrieve Owner method. To list the owners of a funding recipient, you need its recipientId. Our gateway returned the recipientId in the response of the Create Funding Recipient method. If you don't have the recipientId, use our List Funding Recipients method to search for the funding recipient. Our gateway returns the following information about each owner in the list: Name, date of birth, and address. Contact details, including their email address. Relationship to the funding recipient. Our gateway also returns the ownerId, which you can use to perform follow-on actions.", "refs": { "workflowIds": [ "delete-an-owner", "manage-funding-recipients" ], "operationIds": [ "listFundRecipientOwners" ] } }, { "route": "/api/list-funding-account", "type": "reference", "title": "List funding accounts", "description": "GET /funding-accounts", "headings": [], "plainText": "Use this method to return a paginated list of funding accounts associated with your account. Note: If you want to view the details of a specific funding account and you have its fundingAccountId, use our Retrieve Funding Account method. Our gateway returns the following information about each funding account in the list: Name of the account holder and ACH details for the account. Status of the account. Whether we send funds to the account, withdraw funds from the account, or both. For each funding account, we also return the fundingAccountId, which you can use to perform follow-on actions.", "refs": { "workflowIds": [ "delete-a-funding-account", "update-a-funding-account" ], "operationIds": [ "listFundingAccount" ] } }, { "route": "/api/list-funding-recipients", "type": "reference", "title": "List funding recipients", "description": "GET /funding-recipients", "headings": [], "plainText": "Use this method to return a paginated list of funding recipients linked to your account. Note: If you want to view the details of a specific funding recipient and you have its recipientId, use our Retrieve Funding Recipient method. Our gateway returns the following information about each funding recipient in the list: Tax ID and Doing Business As (DBA) name. Address and contact details. Funding accounts linked to the funding recipient. For each funding recipient, we also return the recipientId, which you can use to perform follow-on actions.", "refs": { "workflowIds": [ "delete-a-funding-recipient", "manage-funding-recipients", "update-a-funding-recipient" ], "operationIds": [ "listFundingRecipients" ] } }, { "route": "/api/list-instructions", "type": "reference", "title": "List funding instructions", "description": "GET /funding-instructions", "headings": [], "plainText": "Important: You can return a list of funding instructions from only the previous two years. If you want to view a funding instruction from more than two years ago and you have its instructionId, use our Retrieve Funding Instruction method. Use this method to return a paginated list of funding instructions within a specific date range. Note: If you want to view the details of a specific funding instruction and you have its instructionId, use our Retrieve Funding Instruction method. Our gateway returns the following information for each instruction in the list: Status of the funding instruction. Funding information, including which merchant's funding balance we distribute and the funding account that we send the balance to. For each funding instruction, we also return the instructionId, which you can use to perform follow-on actions.", "refs": { "workflowIds": [ "delete-a-funding-instruction", "update-a-funding-instruction" ], "operationIds": [ "listInstructions" ] } }, { "route": "/api/list-merchant-locations", "type": "reference", "title": "List merchant platform's processing accounts", "description": "GET /merchant-platforms/{merchantPlatformId}/processing-accounts", "headings": [], "plainText": "Use this method to return a paginated list of processing accounts linked to a merchant platform. Note : If you want to view the details of a specific processing account and you have its processingAccountId, use our Retrieve Processing Account method. Use the query parameters to filter the list of results that we return, for example, to search for only closed processing accounts. To list the processing accounts for a merchant platform, you need its merchantPlatformId. If you don't have the merchantPlatformId, use our List Merchant Platforms method to search for the merchant platform. Our gateway returns the following information about eahc processing account in the list: Business details, including its status, time zone, and address. Owners' details, including their contact details. Funding, pricing, and processing information, including its pricing model and funding accounts. For each processing account, we also return its processingAccountId, which you can use to perform follow-on actions.", "refs": { "workflowIds": [ "review-merchant-hierarchy" ], "operationIds": [ "listMerchantLocations" ] } }, { "route": "/api/list-merchant-owners", "type": "reference", "title": "List owners", "description": "GET /processing-accounts/{processingAccountId}/owners", "headings": [], "plainText": "Use this method to return a list of owners of a processing account. Note: If you want to view the details of a specific owner and you have the ownerId, go to our Retrieve Owner method. To list the owners of a processing account, you need its processingAccountId. If you don't have the processingAccountId, use our List Merchant Platform's Processing Accounts method to search for the processing account. Our gateway returns the following information about each owner in the list: Name, date of birth, and address. Contact details, including their email address. Relationship to the business, including whether they are a control prong or authorized signatory, and their equity stake in the business.", "refs": { "workflowIds": [ "review-merchant-hierarchy", "update-an-owner" ], "operationIds": [ "listMerchantOwners" ] } }, { "route": "/api/list-merchant-platforms", "type": "reference", "title": "List merchant platforms", "description": "GET /merchant-platforms", "headings": [], "plainText": "Use this method to return a paginated list of merchant platforms that are linked to your ISV account. Note : If you want to view the details of a specific merchant platform and you have its merchantPlatformId, use our Retrieve Merchant Platform method. Our gateway returns the following information about each merchant platform in the list: Legal information, including its legal name and address. Contact information, including the email address for the business. Processing account information, including the processingAccountId and status of each processing account that's linked to the merchant platform. For each merchant platform, we also return its merchantPlatformId and its linked processingAccountIds, which you can use to perform follow-on actions.", "refs": { "workflowIds": [ "review-merchant-hierarchy" ], "operationIds": [ "listMerchantPlatforms" ] } }, { "route": "/api/list-payment-link-share-events", "type": "reference", "title": "List payment link sharing events", "description": "GET /payment-links/{paymentLinkId}/sharing-events", "headings": [], "plainText": "Use this method to return a paginated list of sharing events for a payment link. A sharing event occurs when a merchant shares a payment link with a customer. To list the sharing events for a payment link, you need its paymentLinkId. Our gateway returned the paymentLinkId in the response of the Create Payment Link method. Note: If you don't have the paymentLinkId, use our List Payment Links method to search for the payment link. Use query parameters to filter the list of results that we return, for example, to search for links sent to a specific customer. Our gateway returns the following information for each sharing event in the list: Customer that the merchant sent the link to. Date that the merchant sent the link.", "refs": { "workflowIds": [ "collect-with-payment-link" ], "operationIds": [ "listPaymentLinkShareEvents" ] } }, { "route": "/api/list-payment-links", "type": "reference", "title": "List payment links", "description": "GET /processing-terminals/{processingTerminalId}/payment-links", "headings": [], "plainText": "Use this method to return a paginated list of payment links linked to a processing terminal. Note: If you want to view the details of a specific payment link and you have its paymentLinkId, use our Retrieve Payment Link method. Use query parameters to filter the list of results that we return, for example, to search for only active links or multi-use links. Our gateway returns the following information about each payment link in the list: type - Indicates whether the link can be used only once or if it can be used multiple times. authType - Indicates whether the transaction is a sale or a pre-authorization. paymentMethods - Indicates the payment method that the merchant accepts. charge - Indicates whether the merchant or the customer enters the amount for the transaction. status - Indicates if the payment link is active. For each payment link, we also return a paymentLinkId, which you can use for follow-on actions.", "refs": { "workflowIds": [ "collect-with-payment-link" ], "operationIds": [ "listPaymentLinks" ] } }, { "route": "/api/list-payment-plans", "type": "reference", "title": "List payment plans", "description": "GET /processing-terminals/{processingTerminalId}/payment-plans", "headings": [], "plainText": "Use this method to return a paginated list of payment plans for a processing terminal. Note: If you want to view the details of a specific payment plan and you have its paymentPlanId, use our Retrieve Payment Plan method. Our gateway returns the following information about each payment plan in the list: Name, length, and currency of the plan How often our gateway collects each payment How much our gateway collects for each payment What happens if the merchant updates or deletes the plan For each payment plan, we return the paymentPlanId, which you can use to perform follow-on actions.", "refs": { "workflowIds": [ "delete-a-payment-plan", "manage-payment-plans", "update-a-payment-plan" ], "operationIds": [ "listPaymentPlans" ] } }, { "route": "/api/list-payments", "type": "reference", "title": "List payments", "description": "GET /payments", "headings": [], "plainText": "Use this method to return a paginated list of payments. Note: If you want to view the details of a specific payment and you have its paymentId, use our Retrieve Payment method. Use query parameters to filter the list of results that we return, for example, to search for payments for a customer, a tip mode, or a date range. Our gateway returns the following information about each payment in the list: Order details, including the transaction amount and when it was processed. Payment card details, including the masked card number, expiry date, and payment method. Cardholder details, including their contact information and shipping address. Payment details, including the payment type, status, and response. For each transaction, we also return the paymentId and an optional secureTokenId, which you can use to perform follow-on actions.", "refs": { "workflowIds": [ "adjust-a-payment", "refund-a-card-payment", "reverse-a-card-payment" ], "operationIds": [ "listPayments" ] } }, { "route": "/api/list-pricing-intents", "type": "reference", "title": "List pricing intents", "description": "GET /pricing-intents", "headings": [], "plainText": "Use this method to return a paginated list of pricing intents associated with the ISV. Note: If you want to view the details of a specific pricing intent and you have its pricingIntentId, use our Retrieve Pricing Intent method. Our gateway returns the following information about each pricing intent in the list: Information about the fees, including the base fees, gateway fees, and processor fees. Status of the pricing intent, including whether we approved the pricing intent. For each pricing intent, we also return its pricingIntentId which you can use to perform follow-on actions.", "refs": { "workflowIds": [ "manage-pricing-intents" ], "operationIds": [ "listPricingIntents" ] } }, { "route": "/api/list-processing-account-contacts", "type": "reference", "title": "List contacts", "description": "GET /processing-accounts/{processingAccountId}/contacts", "headings": [], "plainText": "Use this method to return a list of contacts for a processing account. Note: If you want to view the details of a specific contact and you have their contactId, use our Retrieve Contact method. To list contacts for a processing account, you need the processingAccountId. Our gateway returned the processingAccountId in the response of the Create Merchant Platform method or the Create Processing Account method. Our gateway returns the following information about each contact: Name and contact method, including their phone number or mobile number. Role within the business, for example, if they are a manager. For each contact, we also return a contactId, which you can use to perform follow-on actions.", "refs": { "workflowIds": [ "delete-a-contact", "review-merchant-hierarchy", "update-a-contact" ], "operationIds": [ "listProcessingAccountContacts" ] } }, { "route": "/api/list-processing-accounts-funding-accounts", "type": "reference", "title": "List processing account's funding accounts", "description": "GET /processing-accounts/{processingAccountId}/funding-accounts", "headings": [], "plainText": "Use this method to return a list of funding accounts linked to a processing acccount. To retrieve a list of funding accounts for a processing account, you need the processingAccountId. Our gateway returned the processingAccountId in the response of the Create Merchant Platform method or the Create Proccessing Account method. Our gateway returns information about the following for each funding account in the list: Account information, including the name on the account and payment methods. Status, including whether we have approved or rejected the account. For each funding account, we also return its fundingAccountId, which you can use to perform follow-on actions.", "refs": { "workflowIds": [ "review-merchant-hierarchy" ], "operationIds": [ "listProcessingAccountsFundingAccounts" ] } }, { "route": "/api/list-processing-accounts-processing-terminals", "type": "reference", "title": "List processing terminals", "description": "GET /processing-accounts/{processingAccountId}/processing-terminals", "headings": [], "plainText": "Use this method to return a paginated list of processing terminals associated with a processing account. Note: If you want to view the details of a specific processing terminal and you have its processingTerminalId, use our Retrieve Processing Terminal method. To list the terminals for a processing account, you need its processingAccountId. If you don't have the processingAccountId, use our List Merchant Platforms method to search for a merchant platform and its processing accounts. Our gateway returns the following information for each processing terminal in the list: Status indicating whether the terminal is active or inactive. Configuration settings, including gateway settings and application settings. Features, receipt settings, and security settings. Devices that use the processing terminal's configuration. For each processing terminal, we also return its processingTerminalId, which you can use to perform follow-on actions.", "refs": { "workflowIds": [ "review-merchant-hierarchy" ], "operationIds": [ "listProcessingAccountsProcessingTerminals" ] } }, { "route": "/api/list-processing-accounts-terminal-orders", "type": "reference", "title": "List terminal orders", "description": "GET /processing-accounts/{processingAccountId}/terminal-orders", "headings": [], "plainText": "Use this method to return a paginated list of terminal orders associated with a processing account. Note: If you want to view the details of a specific terminal order and you have its terminalOrderId, use our Retrieve Terminal Order method. Use the query parameters to filter the list of results that we return, for example, to search for terminal orders by their status. To list the terminal orders for a processing account, you need its processingAccountId. If you don't have the processingAccountId, use our List Merchant Platforms method to search for a merchant platform and its processing accounts. Our gateway returns the following information for each terminal order in the list: Status of the order Items in the order Training provider Shipping information For each terminal order, we also return its terminalOrderId, which you can use to perform follow-on actions.", "refs": { "workflowIds": [ "review-merchant-hierarchy" ], "operationIds": [ "listProcessingAccountsTerminalOrders" ] } }, { "route": "/api/list-refunds", "type": "reference", "title": "List refunds", "description": "GET /refunds", "headings": [], "plainText": "Use this method to return a paginated list of refunds. Note: If you want to view the details of a specific refund and you have its refundId, use our Retrieve Refund method. Use query parameters to filter the list of results that we return, for example, to search for refunds for a customer, a tender type, or a date range. Our gateway returns the following information about each refund in the list: Order details, including the refund amount and when we processed the refund. Payment card details, including the masked card number, expiry date, and payment method. Cardholder details, including their contact information and shipping address. For referenced refunds, our gateway also returns details about the payment that the refund is linked to.", "refs": { "workflowIds": [ "adjust-a-refund", "reverse-a-refund" ], "operationIds": [ "listRefunds" ] } }, { "route": "/api/list-secure-tokens", "type": "reference", "title": "List secure tokens", "description": "GET /processing-terminals/{processingTerminalId}/secure-tokens", "headings": [], "plainText": "Use this method to return a paginated list of secure tokens. Note: If you want to view the details of a specific secure token and you have its secureTokenId, use our Retrieve Secure Token method. Use query parameters to filter the list of results that we return, for example, to search for secure tokens by customer or by the first four digits of a card number. Our gateway returns information about the following for each secure token in the list: Payment details that the secure token represents. Customer details, including shipping and billing addresses. Secure token that you can use to carry out transactions. For each secure token, we also return the secureTokenId, which you can use to perform follow-on actions.", "refs": { "workflowIds": [ "delete-a-saved-payment-method", "refresh-a-saved-payment-method", "update-a-saved-payment-method" ], "operationIds": [ "listSecureTokens" ] } }, { "route": "/api/list-subscriptions", "type": "reference", "title": "List subscriptions", "description": "GET /processing-terminals/{processingTerminalId}/subscriptions", "headings": [], "plainText": "Use this method to return a paginated list of subscriptions. Note: If you want to view the details of a specific subscription and you have its subscriptionId, use our Retrieve subscription method. Use query parameters to filter the list of results that we return, for example, to search for subscriptions for a customer, a payment plan, or frequency. Our gateway returns information about the following for each subscription in the list: Payment plan the subscription is linked to. Secure token that represents cardholder’s payment details. Current state of the subscription, including its status, next due date, and invoices. Fees for setup and the cost of the recurring order. Subscription length, end date, and frequency. For each subscription, we also return the subscriptionId, the paymentPlanId, and the secureTokenId, which you can use to perform follow-actions.", "refs": { "workflowIds": [ "manage-subscriptions" ], "operationIds": [ "listSubscriptions" ] } }, { "route": "/api/metadata", "type": "guide", "title": "Metadata", "description": "Guide to using metadata in the Payroc API — attaching custom key-value pairs to resources for auditing, troubleshooting, and third-party system integration.", "headings": [ "What we do with metadata", "Metadata best practices", "How to add metadata to your request", "Worked example 1 - single resource in a request", "Request", "Request", "Worked example 2 - multiple resources in one request", "Request", "Request" ], "plainText": "Metadata is a feature of our API that you can use to attach additional information to a resource without changing how the resource behaves. You can use metadata to store small pieces of contextual data that aren't part of the standard API fields, for example, who created the resource or how it maps to your internal systems. Send your metadata as a set of key-value pairs for your own reference, auditing, or troubleshooting. When you retrieve a resource with attached metadata, we echo back the information exactly as you provided it. What we do with metadata We don't consume metadata or use it for any internal purposes, but we do: Validate its structure to make sure that it contains key-value pairs. Encrypt it and store it with the resource that you link it to. Return it when you retrieve the resource that it's attached to. Metadata best practices Important: Never send sensitive information in metadata, for example, customer information, payment card details, or API keys. Apply the following best practices when you add metadata to your requests: Use unique key names. Always validate your integration. If you send metadata in the wrong format, we reject the whole request and return a 400 error. Never display metadata in a customer-facing user interface. How to add metadata to your request If you send a request that supports metadata, send the metadata object with a series of key-value pairs. You should be aware of the following constraints: You can send up to 20 unique key-value pairs. We accept keys that are String format with a maximum of 50 characters. We accept values that are String format with a maximum of 1024 characters. You can't send nested JSON objects. Some requests support adding metadata to more than one resource. Our worked examples below cover how to add metadata to one resource in a request, and also how to add metadata to two resources in one request. Worked example 1 - single resource in a request I’m integrating against the Create Event Subscription m", "refs": { "workflowIds": [], "operationIds": [ "createEventSubscription", "createInstruction" ] } }, { "route": "/api/pagination", "type": "guide", "title": "Pagination", "description": "How to use cursor-based pagination with the Payroc API, including request parameters, response fields, and navigating pages of results.", "headings": [ "Request parameters", "Example request", "Response fields", "Example response" ], "plainText": "Pagination is a feature of our API that you can use to handle responses that contain large datasets, for example, when you retrieve a list of payments. Instead of returning all the results in one response, we separate the results into pages and return a page for each request. You can then send follow-up requests to retrieve the other pages. Request parameters If a method supports pagination, you can use the following query parameters to tailor your results: before - Return results that are before the value that you specify. You can't use the before parameter in the same request as the after parameter. after - Return results that are after the value that you specify. You can't use the after parameter in the same request as the before parameter. limit - Specify the maximum number of results we return for each page. If you don't include a limit parameter, we return a maximum of 10 results for each page. Note: To retrieve the first page of results, don't include a before parameter or an after parameter in your request. Example request The following example is a request to our List Contacts method. The request limits the results for each page to two results: curl -G https://api.payroc.com/v1/processing-accounts/38765/contacts \\ -H \"Authorization: Bearer \" \\ -d limit=2 Response fields We return the following fields in the response: limit - Maximum number of results that a page can contain. count - Number of results that we returned in the page. hasMore - Boolean that indicates if there are more results available. If the value is false, you have reached the last page of results. data - Array that contains your results. links - HATEOAS object that contains information about how to navigate to additional pages of results. The object contains the following fields: rel - Relationship of the link to the current page. The value is one of the following:next - Next page of results. previous – Previous page of results. method - HTTP method that you use to retrieve the next p", "refs": { "workflowIds": [], "operationIds": [ "listProcessingAccountContacts" ] } }, { "route": "/api/patch-event-subscription", "type": "reference", "title": "Partially update event subscription", "description": "PATCH /event-subscriptions/{subscriptionId}", "headings": [], "plainText": "Use this method to partially update an event subscription. Structure your request to follow the RFC 6902 standard. To update an event subscription, you need its subscriptionId. Our gateway returned the subscriptionId in the id field in the response of the Create Event Subscription method. Note: If you don't have the subscriptionId, use our List Event Subscriptions method to search for the subscription. You can update the following properties of an event subscription: eventTypes - Subscribe to new events or remove events that you are subscribed to. notifications - Information about your endpoint and who we email if we can't contact your endpoint. enabled - Turn on or turn off notifications for the subscription.", "refs": { "workflowIds": [ "patch-an-event-subscription" ], "operationIds": [ "patchEventSubscription" ] } }, { "route": "/api/patch-pricing-intent", "type": "reference", "title": "Partially update pricing intent", "description": "PATCH /pricing-intents/{pricingIntentId}", "headings": [], "plainText": "Use this method to partially update a pricing intent. Structure your request to follow the RFC 6902 standard. If you update a pricing intent, it won't affect merchants you've previously onboarded. To update a pricing intent, you need its pricingIntentId. Our gateway returned the pricingIntentId in the response of the Create Pricing Intent method. Note: If you don't have the pricingIntentId, use our List Pricing Intents method to search for the pricing intent. You can update the following details about a pricing intent: Fees, including the base fees, processor fees, and gateway fees. Custom name for the pricing intent. Additional services that merchants can sign up for.", "refs": { "workflowIds": [ "patch-a-pricing-intent" ], "operationIds": [ "patchPricingIntent" ] } }, { "route": "/api/pay-subscription", "type": "reference", "title": "Pay manual subscription", "description": "POST /processing-terminals/{processingTerminalId}/subscriptions/{subscriptionId}/pay", "headings": [], "plainText": "Use this method to manually collect a payment linked to a subscription. You can manually collect a payment only if the merchant chose not to let our gateway automatically collect each payment. To manually collect a payment, you need the subscriptionId of the subscription that's linked to the payment. You sent the subscriptionId in the request of the Create Subscription method. Note: If you don't have the subscriptionId, use our List Subscriptions method to search for the subscription. The request includes an order object that contains information about the amount that you want to collect. In the response, our gateway returns information about the payment and a paymentId. You can use the paymentId in follow-on actions with the Payments endpoints or Bank Transfer Payments endpoints.", "refs": { "workflowIds": [ "manage-subscriptions" ], "operationIds": [ "paySubscription" ] } }, { "route": "/api/payment", "type": "reference", "title": "Create payment", "description": "POST /payments", "headings": [], "plainText": "Use this method to run a sale or a pre-authorization with a customer's payment card. In the response, our gateway returns information about the card payment and a paymentId, which you need for the following methods: Retrieve payment - View the details of the card payment. Adjust payment - Update the details of the card payment. Capture payment - Capture the pre-authorization. Reverse payment - Cancel the card payment if it's in an open batch. Refund payment - Run a referenced refund to return funds to the payment card. Payment methods Cards - Credit, debit, and EBT Digital wallets - Apple Pay® and Google Pay® Tokens - Secure tokens and single-use tokens Features Our Create Payment method also supports the following features: Repeat payments - Run multiple payments as part of a payment schedule that you manage with your own software. Offline sales - Run a sale or a pre-authorization if the terminal loses its connection to our gateway. Tokenization - Save card details to use in future transactions. 3-D Secure - Verify the identity of the cardholder. Custom fields - Add your own data to a payment. Tips - Add tips to the card payment. Taxes - Add local taxes to the card payment. Surcharging - Add a surcharge to the card payment. Dual pricing - Offer different prices based on payment method, for example, if you use our RewardPay Choice pricing program. Healthcare - Accept payments from Health Savings Accounts (HSA) and Flexible Spending Accounts (FSA).", "refs": { "workflowIds": [ "accept-apple-pay", "accept-google-pay", "collect-with-hosted-fields", "pay-with-single-use-token", "run-a-card-sale", "run-a-pre-authorization" ], "operationIds": [ "payment" ] } }, { "route": "/api/postman-collection", "type": "guide", "title": "Postman Collection", "description": "Step-by-step guide to setting up and authorizing the Payroc Postman collection for testing API requests.", "headings": [ "Create a Postman API key", "Copy our repository", "Authorize your requests" ], "plainText": "Important: Before you begin, contact our Sales Team to set up your Payroc account and to get your API key. To use our Postman collection, you need to: Create a Postman API key. Clone our repository. Authorize your requests. Create a Postman API key Go to https://postman.co/settings/me/api-keys. Postman might prompt you to sign in. Select Generate API Key. In the Name your key field, enter Payroc-API, and then select Generate API Key. Copy and save your Postman API key. Copy our repository Go to https://github.com/payroc/api-postman-collections. Go to Releases and download the zip file. Extract the contents of the file. Open a PowerShell terminal, and then run the Setup.ps1 script in the terminal. In the PowerShell terminal, the script prompts you to enter your Postman API key and then enter your Payroc API Key. Note: If you get the error Setup.ps1 cannot be loaded because running scripts is disabled on this system, it means that you don't have permission to run this script. To bypass this issue, use: powershell -ExecutionPolicy Bypass -File .\\Setup.ps1 Authorize your requests To automatically populate each request with a bearer token, complete the following steps: Launch the Postman application. From the Workspaces dropdown menu, select Payroc-API. Select Collections, and then select Payroc Identity Service, and then select the Authorize request. Authorize request From the Environment dropdown menu, select Payroc-UAT. Payroc UAT To send the Authorize request, select Send. Note: If your token expires, send the Authorize request again.", "refs": { "workflowIds": [], "operationIds": [] } }, { "route": "/api/reactivate-subscription", "type": "reference", "title": "Re-activate subscription", "description": "POST /processing-terminals/{processingTerminalId}/subscriptions/{subscriptionId}/reactivate", "headings": [], "plainText": "Use this method to reactivate a subscription. To reactivate a subscription, you need its subscriptionId, which you sent in the request of the Create Subscription method. Note: If you don't have the subscriptionId, use our List Subscriptions method to search for the subscription. If your request is successful, our gateway restarts taking payments from the customer. To deactivate the subscription, use our Deactivate Subscription method.", "refs": { "workflowIds": [ "reactivate-a-subscription" ], "operationIds": [ "reactivateSubscription" ] } }, { "route": "/api/refund-bank-transfer-payment", "type": "reference", "title": "Create referenced refund", "description": "POST /bank-transfer-payments/{paymentId}/refund", "headings": [], "plainText": "Use this method to refund a bank transfer payment that is in a closed batch. To refund a bank transfer payment, you need its paymentId. Our gateway returned the paymentId in the response of the Create Payment method. Note: If you don’t have the paymentId, use our List Payments method to search for the bank transfer payment. If your refund is successful, our gateway returns the payment amount to the customer's account. Things to consider If the merchant refunds a bank transfer payment that is in an open batch, our gateway reverses the bank transfer payment. Some merchants can run unreferenced refunds, which means that they don’t need a paymentId to return an amount to a customer. For more information about how to run an unreferenced refund, go to Create Refund .", "refs": { "workflowIds": [ "refund-a-bank-transfer-payment" ], "operationIds": [ "refundBankTransferPayment" ] } }, { "route": "/api/refund-payment", "type": "reference", "title": "Create referenced refund", "description": "POST /payments/{paymentId}/refund", "headings": [], "plainText": "Use this method to refund a payment that is in a closed batch. To refund a payment, you need its paymentId. Our gateway returned the paymentId in the response of the Create Payment method. Note: If you don't have the paymentId, use our List Payments method to search for the payment. If your refund is successful, our gateway returns the payment amount to the cardholder's account. Things to consider If the merchant refunds a payment that is in an open batch, our gateway reverses the payment. Some merchants can run unreferenced refunds, which means that they don't need a paymentId to return an amount to a customer. For more information about how to run an unreferenced refund, go to Create Refund .", "refs": { "workflowIds": [ "refund-a-card-payment", "run-a-pre-authorization" ], "operationIds": [ "refundPayment" ] } }, { "route": "/api/represent-bank-transfer-payment", "type": "reference", "title": "Re-present payment", "description": "POST /bank-transfer-payments/{paymentId}/represent", "headings": [], "plainText": "Use this method to re-present an ACH payment. To re-present a payment, you need the paymentId of the return. To get the paymentId of the return, complete the following steps: Use our Retrieve Payment method to view the details of the original payment. From the returns object in the response, get the paymentId of the return. Our gateway uses the bank account details from the original payment. If you want to update the customer's bank account details, send the new bank account details in the request. If your request is successful, our gateway re-presents the payment.", "refs": { "workflowIds": [ "represent-ach-payment" ], "operationIds": [ "representBankTransferPayment" ] } }, { "route": "/api/resources", "type": "guide", "title": "API resources", "description": "Authored introductions to resources in the canonical payment API.", "headings": [], "plainText": "Authored introductions to resources in the canonical payment API. Bank transfer payments Bank transfer refunds Card Payments Card payment refunds Contacts Event Subscriptions Funding Accounts Funding Activity Funding Instructions Funding Recipients Merchant Platforms Owners Payment Features - Cards Payment Links Payroc Cloud Pricing Intents Processing accounts Processing terminals Payment Plans Subscriptions Secure tokens", "refs": { "workflowIds": [], "operationIds": [] } }, { "route": "/api/resources/bank-transfer-payments", "type": "guide", "title": "Bank transfer payments", "description": "Reference for the bank transfer payment endpoints, covering how to create, retrieve, list, and re-present payments taken from a customer's bank account.", "headings": [ "Retrieve the details of the transaction", "Re-present the transaction", "Close the transaction" ], "plainText": "Use our Bank Transfer Payments endpoints to take payments from a customer’s bank account. Integrate with our Create Payment method to run a sale. When you send a successful request, our gateway returns a paymentId for the transaction, which you can use to: Retrieve the details of the transaction Integrate with our Retrieve Payment method to view transaction details for a specific transaction, such as the order information, the bank account details, and the transaction result. Integrate with our List Payments method to return a paginated list of transactions that meet specific query parameters. Re-present the transaction Integrate with our Re-present Payment method to resubmit a declined transaction. Close the transaction Integrate with our Close Return method to close a returned transaction without re-presenting it.", "refs": { "workflowIds": [], "operationIds": [ "bankTransferPayment", "closeBankTransferPayment", "getBankTransferPayment", "listBankTransferPayments", "representBankTransferPayment" ] } }, { "route": "/api/resources/bank-transfer-refunds", "type": "guide", "title": "Bank transfer refunds", "description": "Reference for the bank transfer refund endpoints, covering how to reverse, refund, retrieve, list, and reverse refunds for bank transfer payments.", "headings": [ "Reverse or refund a payment", "Retrieve the details of the refund", "Reverse the refund" ], "plainText": "Use our Bank Transfer Refunds endpoints to reverse or refund a payment and manage refunds. Reverse or refund a payment We have three methods to reverse or refund a payment: If the payment is in an open batch, the merchant must cancel the payment. To cancel a payment, integrate with our Reverse Payment method. If the payment is in a closed batch and the merchant has the paymentId of the payment, the merchant must refund the payment. To refund a payment, integrate with our Create Referenced Refund method. If the payment is in a closed batch and the merchant doesn’t have the paymentId of the payment, the merchant must run an unreferenced refund. To run an unreferenced refund, integrate with our Create Unreferenced Refund method. Note: If the merchant refunds a payment in an open batch, our gateway treats the payment as a reversal and cancels it. Retrieve the details of the refund Integrate with our Retrieve Refund method to view the details of a refund, such as the refund amount, the bank account details, and the transaction result. Integrate with our List Refunds method to return a paginated list of refunds that meet specific query parameters. Reverse the refund Integrate with our Reverse Refund method to cancel a refund if it’s in an open batch.", "refs": { "workflowIds": [], "operationIds": [ "bankTransferUnreferencedRefund", "getBankTransferRefund", "listBankTransferRefunds", "refundBankTransferPayment", "reverseBankTransferPayment", "reverseBankTransferRefund" ] } }, { "route": "/api/resources/card-payments", "type": "guide", "title": "Card Payments", "description": "Reference for the card payment endpoints, covering how to create, retrieve, list, adjust, and capture payments taken from a card.", "headings": [ "Retrieve the details of the transaction", "Adjust the details of the transaction", "Capture the transaction" ], "plainText": "Use our Payments endpoints to take payments from a card in card-present environments, e‑Commerce environments, or MOTO environments. Integrate with our Create Payment method to run a sale or a pre-authorization . When you send a successful request, our gateway returns a paymentId for the transaction, which you can use to: Retrieve the details of the transaction Integrate with our Retrieve Payment method to view transaction details for a specific transaction, such as the order information, the payment card details, and the transaction result. Integrate with our List Payments method to return a paginated list of transactions that meet specific query parameters. Adjust the details of the transaction Integrate with our Adjust Payment method to change the following details of a transaction: Order amount and tip amount Status of the transaction Cardholder’s shipping address and contact information Cardholder’s signature Capture the transaction Integrate with our Capture Payment method to capture a pre-authorization. Note: To capture more than the pre-authorization amount, we recommend that the merchant adjusts the pre-authorization amount before they capture it. To do this, we recommend that you integrate with our Adjust Payment method.", "refs": { "workflowIds": [], "operationIds": [ "adjustPayment", "capturePayment", "getPayment", "listPayments", "payment" ] } }, { "route": "/api/resources/card-refunds", "type": "guide", "title": "Card payment refunds", "description": "Reference for the card refund endpoints, covering how to reverse, refund, retrieve, list, adjust, and reverse refunds for card transactions.", "headings": [ "Reverse or refund a transaction", "Retrieve the details of the refund", "Adjust the refund", "Reverse the refund" ], "plainText": "Use our Card Refunds endpoints to reverse or refund a transaction and manage refunds. Reverse or refund a transaction We have three methods to reverse or refund a transaction: If the transaction is in an open batch, the merchant must cancel the transaction. To cancel a transaction, integrate with our Reverse Payment method. If the transaction is in a closed batch and the merchant has the paymentId of the transaction, the merchant must refund the transaction. To refund a transaction, integrate with our Create Referenced Refund method. If the transaction is in a closed batch and the merchant doesn't have the paymentId of the transaction, the merchant must run an unreferenced refund. To run an unreferenced refund, integrate with our Create Unreferenced Refund method. Note: If the merchant refunds a transaction in an open batch, our gateway treats the transaction as a reversal and cancels it. Retrieve the details of the refund Integrate with our Retrieve Refund method to view the details of a refund, such as the refund amount, the payment card details, and the status of the refund. Integrate with our List Refunds method to return a paginated list of refunds that meet specific query parameters. Adjust the refund Integrate with our Adjust Refund method to update the details of a refund, such as customer details and the status of the refund. Reverse the refund Integrate with our Reverse Refund method to cancel a refund if it's in an open batch.", "refs": { "workflowIds": [], "operationIds": [ "adjustRefund", "getRefund", "listRefunds", "refundPayment", "reversePayment", "reverseRefund", "unreferencedRefund" ] } }, { "route": "/api/resources/cards", "type": "guide", "title": "Payment Features - Cards", "description": "Reference for the card payment feature endpoints, covering how to verify a card, view an EBT balance, look up BIN information, and check DCC eligibility.", "headings": [ "Verify a card", "View EBT balance", "Look up BIN information", "Verify a card's DCC eligibility" ], "plainText": "Use our Cards endpoints to check if a card is valid and has available balance, or to check if a card is eligible for Dynamic Currency Conversion (DCC) . Verify a card Integrate with our Verify Card method to check if the details of a payment card are correct and that you can run transactions with the payment card. View EBT balance Integrate with our View EBT Balance method to view the balance on an EBT card. Look up BIN information Integrate with our Look Up BIN Information method to view the details of a payment card, including the currency of the card and if the card is eligible for surcharging. Verify a card's DCC eligibility Integrate with our Verify DCC Eligibility method to check if a payment card is eligible for DCC, and to provide the conversion rates that the merchant can offer the customer.", "refs": { "workflowIds": [], "operationIds": [ "balanceCard", "binLookup", "getFxRates", "verifyCard" ] } }, { "route": "/api/resources/contacts", "type": "guide", "title": "Contacts", "description": "Reference for the contact endpoints, covering how to retrieve, update, and delete a contact linked to a processing account.", "headings": [ "Retrieve the details of a contact", "Update the details of a contact", "Delete a contact" ], "plainText": "Use our Contacts endpoints to retrieve, update, or delete a contact associated with a processing account. Retrieve the details of a contact Integrate with our Retrieve Contact method to view the details of a contact, such as their name, contact details, and role within the business. Update the details of a contact Integrate with our Update Contact method to update the details of a contact, such as their name, contact details, and role within the business. Delete a contact Integrate with our Delete Contact method to delete a contact.", "refs": { "workflowIds": [], "operationIds": [ "deleteContact", "getContact", "updateContact" ] } }, { "route": "/api/resources/event-subscriptions", "type": "guide", "title": "Event Subscriptions", "description": "Reference for the event subscription endpoints, covering how to create, retrieve, list, update, and delete subscriptions that send you notifications when a resource changes.", "headings": [], "plainText": "Use our Event Subscriptions endpoints to create and manage the events you have subscribed to. We trigger an event when we make a change to a resource or complete a process, for example, when we change the status of a processing account. When you subscribe to an event, we send you a notification each time we trigger the event. Integrate with our Create Event Subscription method to subscribe to an event. When you send a successful request our gateway returns an id for the subscription, which you use to complete follow-on actions: Retrieve Event Subscription - View the details of the event subscription. If you don't have the subscriptionId, use our List Event Subscriptions method. Update Event Subscription - Update the details of the event subscription, including the events that you have subscribed to. You can also partially update the event subscription. Delete Event Subscription - Delete the event subscription. Note: When you create an event subscription, we return a unique identifier for the event subscription in the id field. Send this unique identifier in your requests when we require a subscriptionId.", "refs": { "workflowIds": [], "operationIds": [ "createEventSubscription", "deleteEventSubscription", "getEventSubscription", "listEventSubscriptions", "patchEventSubscription", "updateEventSubscription" ] } }, { "route": "/api/resources/funding-accounts", "type": "guide", "title": "Funding Accounts", "description": "Reference for the funding account endpoints, covering how to retrieve, list, update, and delete funding accounts linked to processing accounts and funding recipients.", "headings": [ "Retrieve information about a funding account", "Update the details of a funding account", "Delete a funding account" ], "plainText": "Use our Funding Accounts endpoints to manage funding accounts associated with processing accounts and funding recipients. Retrieve information about a funding account Integrate with our Retrieve Funding Account method to retrieve information about a specific funding account. Integrate with our List Funding Accounts method to return a list of all funding accounts associated with your account. Update the details of a funding account Integrate with our Update Funding Account method to make changes to a funding account that is associated with a funding recipient. Delete a funding account Integrate with our Delete Funding Account method to delete a funding account that is associated with a funding recipient.", "refs": { "workflowIds": [], "operationIds": [ "deleteFundingAccount", "getFundingAccount", "listFundingAccount", "updateFundingAccount" ] } }, { "route": "/api/resources/funding-activity", "type": "guide", "title": "Funding Activity", "description": "Reference for the funding activity endpoints, covering how to list funding balances and funding activity for merchants linked to your account.", "headings": [ "List Funding Balances", "List Funding Activity" ], "plainText": "Use our Funding Activity endpoints to retrieve funding information for the merchants that are linked to your account. List Funding Balances Integrate with our List Funding Balances method to return a paginated list of funding balances available for each merchant linked to your account. List Funding Activity Integrate with our List Funding Activity method to return a list of funding activities within a specific date range.", "refs": { "workflowIds": [], "operationIds": [ "getFundingActivity", "getFundingBalance" ] } }, { "route": "/api/resources/funding-instructions", "type": "guide", "title": "Funding Instructions", "description": "Reference for the funding instruction endpoints, covering how to create, retrieve, list, update, and delete instructions that tell us how to distribute funds to your merchants.", "headings": [ "Retrieve the details of a funding instruction", "Update the details of a funding instruction", "Delete a funding instruction" ], "plainText": "Use our Funding Instructions endpoints to manage funding instructions , which tell us how to distribute the funding balance from your merchants' transactions. Integrate with our Create Funding Instruction method to send funds to your merchants. When you send a successful request, our gateway returns an instructionId for the funding instruction, which you can use to: Retrieve the details of a funding instruction Integrate with our Retrieve Funding Instruction method to retrieve the details of a specific funding instruction. Integrate with our List Funding Instructions method to return a paginated list of funding instructions that we received within a specific date range. Update the details of a funding instruction Integrate with our Update Funding Instruction method to make changes to a funding instruction that we haven't yet processed. Delete a funding instruction Integrate with our Delete Funding Instruction method to delete a funding instruction that we haven't yet processed.", "refs": { "workflowIds": [], "operationIds": [ "createInstruction", "deleteInstructions", "getInstruction", "listInstructions", "updateInstructions" ] } }, { "route": "/api/resources/funding-recipients", "type": "guide", "title": "Funding Recipients", "description": "Reference for the funding recipient endpoints, covering how to create, retrieve, list, update, and delete a funding recipient along with its accounts and owners.", "headings": [ "Retrieve information about the funding recipient", "Add a funding account or an owner to a funding recipient", "Update a funding recipient", "Delete a funding recipient" ], "plainText": "Use our Funding Recipient endpoints to create and manage funding recipients , including their accounts and owners. Note: You can use our API to manage owners and funding accounts associated with a funding recipient. For more information about owners and funding accounts, go to Owners overview or our Funding Accounts methods. Integrate with our Create Funding Recipient method to send us information about the funding recipient, including its funding accounts and owners. When you send a successful request, our gateway returns a recipientId for the funding recipient, which you can use to: Retrieve information about the funding recipient Integrate with our Retrieve Funding Recipient method to view the details of a specific funding recipient, such as its funding accounts, owners, and contact details. Integrate with our List Funding Recipients method to return a paginated list of funding recipients linked to your account. Integrate with our List Funding Accounts method to view the funding accounts linked to the funding recipient. Integrate with our List Funding Recipient Owners method to view the owners associated with the funding recipient. Add a funding account or an owner to a funding recipient Integrate with our Create Funding Account method to create a funding account and link it to the funding recipient. Integrate with our Create Funding Recipient Owner method to create an owner and associate them with the funding recipient. Update a funding recipient Integrate with our Update Funding Recipient method to update the details for a funding recipient, for example, its address or contact methods. Delete a funding recipient Integrate with our Delete Funding Recipient method to delete the funding recipient, including its funding accounts and owners.", "refs": { "workflowIds": [], "operationIds": [ "createFundRecipientFundingAccount", "createFundRecipientOwner", "createFundingRecipient", "deleteFundingRecipient", "getFundingRecipient", "listFundRecipientFundingAccounts", "listFundRecipientOwners", "listFundingAccount", "listFundingRecipients", "updateFundingRecipient" ] } }, { "route": "/api/resources/merchant-platforms", "type": "guide", "title": "Merchant Platforms", "description": "Reference for the merchant platform endpoints, covering how to create and retrieve a merchant platform, and how to list and add its processing accounts.", "headings": [ "Retrieve information about a merchant platform", "List the processing accounts of a merchant platform", "Add a processing account to a merchant platform" ], "plainText": "Use our Merchant Platform endpoints to board a merchant. Integrate with our Create Merchant Platform method to send us information about the merchant's business and its processing accounts. Note: If the merchant's business expands after you board them, use our Create Processing Account method to add additional processing accounts and their contacts. When you send a successful request, we review the merchant's information. After we complete our review and approve the merchant, we assign a merchantPlatformId, which you can use to: Retrieve information about a merchant platform Integrate with our Retrieve Merchant Platform method to retrieve information about a merchant platform and its processing accounts. Integrate with our List Merchant Platforms method to return a paginated list of merchant platforms linked to your ISV account. List the processing accounts of a merchant platform Integrate with our List Merchant Platform's Processing Accounts method to return a paginated list of processing accounts linked to a merchant platform. Add a processing account to a merchant platform Integrate with our Create Processing Account method to add a processing account to a merchant platform.", "refs": { "workflowIds": [], "operationIds": [ "createMerchant", "createProcessingAccount", "getMerchantAccounts", "listMerchantLocations", "listMerchantPlatforms" ] } }, { "route": "/api/resources/owners", "type": "guide", "title": "Owners", "description": "Reference for the owner endpoints, covering how to retrieve, update, and delete an owner of a processing account or a funding recipient.", "headings": [ "Retrieve the details of an owner", "Update the details of an owner", "Delete an owner" ], "plainText": "Use our Owners endpoints to retrieve, update, or delete an owner. In our API, there are two types of owners: Owner of a processing account - An individual who owns the relationship between Payroc and the processing account. Use our Create Merchant Platform method or our Create Processing Account method to add an owner to a processing account. Owner of a funding recipient - An individual who is associated with the funding recipient. Use our Create Funding Recipient method or our Create Funding Recipient Owner method to add an owner to a funding recipient. Our gateway assigns an ownerId to each owner, which you can use to: Retrieve the details of an owner Integrate with our Retrieve Owner method to view the details of an owner, such as their name, address, and contact details. Update the details of an owner Important: You can't update the details of an owner of a processing account. Integrate with our Update Owner method to update the details of an owner, such as their name, address, and contact details. Delete an owner Important: You can't delete an owner of a processing account. Integrate with our Delete Owner method to delete an owner from a funding recipient.", "refs": { "workflowIds": [], "operationIds": [ "createFundRecipientOwner", "createFundingRecipient", "createMerchant", "createProcessingAccount", "deleteOwner", "getOwner", "updateOwner" ] } }, { "route": "/api/resources/payment-links", "type": "guide", "title": "Payment Links", "description": "Reference for the payment link endpoints, covering how to create, share, update, retrieve, list, and deactivate a payment link that a customer uses to pay for goods or services.", "headings": [], "plainText": "Use our Payment Links endpoints to create a payment link that a merchant can share with a customer. The customer then uses the link to open a payment page that they use to pay for goods or services. Integrate with our Create Payment Link method to create and configure a payment link. When our gateway receives a successful request, it creates a payment link and returns a paymentLinkId that you use to complete follow-on actions: Share a link - Email a payment link to one or more customers. Update a link - Update a payment link, for example, its expiration date. Retrieve a link - Retrieve the details of a payment link. List payment links - Retrieve a paginated list of payment links for a processing terminal. List a link's sharing events - Retrieve a paginated list of the times a merchant has shared a payment link. Deactivate a link - Deactivate a payment link. Note: If a customer has made a payment using a payment link, you can use our Card Payments endpoints or our Bank Transfer Payments endpoints to manage the payment.", "refs": { "workflowIds": [], "operationIds": [ "createPaymentLink", "deactivatePaymentLink", "listPaymentLinkShareEvents", "listPaymentLinks", "retrievePaymentLink", "sharePaymentLink", "updatePaymentLink" ] } }, { "route": "/api/resources/payment-plans", "type": "guide", "title": "Payment Plans", "description": "Reference for the payment plan endpoints, covering how to create, retrieve, list, update, and delete a schedule that defines how often and how much a gateway collects.", "headings": [], "plainText": "Important: Our solution for repeat payments is very flexible and uses the Payment Plans, Secure Tokens, and Subscriptions endpoints. To help you understand how it works, we recommend that you go to Repeat Payments. Use our Payment Plans endpoints to create payment schedules that you can later assign customers to using our Subscriptions endpoints. A payment plan includes information about: How often our gateway collects a payment. How many payments our gateway collects. How much our gateway collects for each payment. When you create a payment plan, you generate and include a paymentPlanId that you use to complete follow-on actions: Retrieve the payment plan - View the details of a payment plan. If you don't have the paymentPlanId you can use our List Payment Plans method. Update the payment plan - Update the details of a payment plan, including the frequency or amount. Delete the payment plan - Delete the payment plan. After you create the payment plan, use the Subscriptions endpoint to assign customers to the payment plan.", "refs": { "workflowIds": [], "operationIds": [ "createPaymentPlan", "deletePaymentPlan", "getPaymentPlan", "listPaymentPlans", "updatePaymentPlan" ] } }, { "route": "/api/resources/payroc-cloud", "type": "guide", "title": "Payroc Cloud", "description": "Reference for the Payroc Cloud endpoints, covering how to submit, retrieve, and cancel payment, refund, and signature instructions, and how to read a closed-loop card.", "headings": [], "plainText": "Important: Our Payroc Cloud endpoints are part of a larger Payroc Cloud solution. To help you understand how it works, go to Payroc Cloud. Use our Payroc Cloud endpoints to submit instructions to a payment device. You can use Payroc Cloud to: Take a payment - Initiate, retrieve, and cancel a payment instruction. Run a refund - Initiate, retrieve, and cancel a refund instruction. Capture a signature - Initiate, retrieve, and cancel a signature instruction. Read a closed-loop card - Retrieve the details of a closed-loop card .", "refs": { "workflowIds": [], "operationIds": [ "deletePaymentInstruction", "deleteRefundInstruction", "deleteSignatureInstruction", "getClosedLoop", "getPaymentInstruction", "getRefundInstruction", "getSignatureInstruction", "sendPaymentInstruction", "sendRefundInstruction", "sendSignatureInstruction" ] } }, { "route": "/api/resources/pricing-intents", "type": "guide", "title": "Pricing Intents", "description": "Reference for the pricing intent endpoints, covering how to create, retrieve, list, update, and delete a template of fees assigned to a processing account.", "headings": [], "plainText": "Use our Pricing Intents endpoints to create a template of fees that you can assign to a processing account. You can create a pricing intent for each processing account, or you can assign a processing account to a pricing intent that you have already created. Note: Before you board a merchant, they must sign a Merchant Processing Agreement (MPA) that describes the fees that they have agreed to pay. Use the information from the MPA to populate the fees in the pricing intent. Use our Create Pricing Intent method to create a pricing intent. When you send a successful request, our gateway returns the id for the pricing intent, which you can use to: Retrieve Pricing Intent - View the details of the pricing intent. If you don't have the id for the pricing intent, use our List Pricing Intents method. Update Pricing Intent - Update the details of the pricing intent, including fees and the custom name of the pricing intent. You can also partially update the pricing intent. Delete Pricing Intent - Delete the pricing intent.", "refs": { "workflowIds": [], "operationIds": [ "createPricingIntent", "deletePricingIntent", "getPricingIntent", "listPricingIntents", "patchPricingIntent", "updatePricingIntent" ] } }, { "route": "/api/resources/processing-accounts", "type": "guide", "title": "Processing accounts", "description": "Reference for the processing account endpoints, covering how to retrieve account details, pricing agreements, funding accounts, owners, contacts, and terminal orders.", "headings": [ "Retrieve processing account", "Get processing account pricing agreement", "Create reminder for processing account", "List processing account's funding accounts", "List owners", "List contacts", "List processing terminals", "Create terminal orders", "List terminal orders", "Upload attachment to processing account" ], "plainText": "Important: You can’t use the Processing Accounts endpoint to add a processing account to a merchant platform. To add a processing account, you need to use the Create Processing Account method in our Merchant Platforms endpoint. Use our Processing Accounts endpoints to retrieve information about a merchant’s processing accounts and terminal orders . You can also use the processing accounts endpoint to send a reminder to a merchant to sign their processing agreement. Retrieve processing account Integrate with our Retrieve Processing Account method to retrieve information associated with a specific processing account, including: Doing Business As (DBA) name Merchant Category code (MCC) Pricing agreement Funding accounts Get processing account pricing agreement Integrate with our Get Processing Account Pricing Agreement method to retrieve information about the pricing structure that the merchant signed up for when we created the processing account. Create reminder for processing account Integrate with our Create Reminder for Processing Account method to send an email reminder to a merchant if they have not yet signed their pricing agreement. List processing account's funding accounts Integrate with our List Processing Account’s Funding Accounts method to retrieve the funding accounts that are linked to a processing account. List owners Integrate with our List Owners method to retrieve the owner or owners of a processing account. List contacts Integrate with our List Contacts method to retrieve a list of contacts associated with the processing account. List processing terminals Integrate with our List Processing Terminals method to retrieve a list of all processing terminals associated with a processing account. Create terminal orders Integrate with our Create Terminal Orders method so that you can order and configure processing terminals for a processing account. List terminal orders Integrate with our List Terminal Orders method to retrieve a list of terminal orders as", "refs": { "workflowIds": [], "operationIds": [ "createProcessingAccount", "createProcessingAccountAttachment", "createReminder", "createTerminalOrder", "getProcessingAccounts", "listMerchantOwners", "listProcessingAccountContacts", "listProcessingAccountsFundingAccounts", "listProcessingAccountsProcessingTerminals", "listProcessingAccountsTerminalOrders", "retrieveProcessingAccountPricing" ] } }, { "route": "/api/resources/processing-terminals", "type": "guide", "title": "Processing terminals", "description": "Reference for the processing terminal endpoints, covering how to retrieve terminal, host, and device configuration details, and how to close a batch.", "headings": [ "Retrieve Processing Terminal", "Retrieve Processing Terminal Host Configuration", "Retrieve device configuration", "Close batch" ], "plainText": "Use our Processing Terminals endpoints to retrieve information about a processing terminal or to close a batch. Retrieve Processing Terminal Integrate with our Retrieve Processing Terminal method to retrieve information about a processing terminal. Retrieve Processing Terminal Host Configuration Integrate with our Retrieve Host Processor Configuration method to retrieve the host configuration of a processing terminal, which you can use to connect a merchant’s account to a third-party gateway. Retrieve device configuration Integrate with our Retrieve device configuration method to retrieve the configuration details for a device model or type. Close batch Integrate with our Close batch method to manually close a batch on a processing terminal.", "refs": { "workflowIds": [], "operationIds": [ "closeBatch", "getProcessingTerminal", "getProcessingTerminalHostConfiguration", "retrieveDeviceConfiguration" ] } }, { "route": "/api/resources/secure-tokens", "type": "guide", "title": "Secure tokens", "description": "Reference for the secure token endpoints, covering how to create, retrieve, list, update, and delete a token that represents a customer's saved payment details.", "headings": [ "Retrieve the details of a token", "Update a token", "Delete a token" ], "plainText": "Use our Secure Tokens endpoints to create and manage a secure token that represents a customer’s payment details. Merchants can use the token to run transactions instead of using the customer’s card or bank details, and they can also store the token without additional PCI compliance requirements. Integrate with the Create Secure Token method to create a secure token. You can then include the token in requests to our gateway, for example, to run a sale or to subscribe a customer to a payment plan. When you create a token, you generate and include a secureTokenId to identify it. You can then use the secureTokenId to manage the token, including the following: Retrieve the details of a token Integrate with our Retrieve Secure Token method to view a token, the customer’s payment details, and the Merchant Initiated Transaction (MIT) agreement. Integrate with our List Secure Tokens to return a paginated list of secure tokens that meet specific query requirements. Update a token Note: If you’re using our Hosted Fields solution, integrate with the Update Account Details method to update a secure token with the details from a single-use token . Integrate with our Update Secure Token method to update the customer’s saved payment details. You can update: Card or bank account details MIT agreement Customer’s contact details Customer’s address details Delete a token Integrate with our Delete Secure Token method to permanently delete a secure token from our vault .", "refs": { "workflowIds": [], "operationIds": [ "accountUpdate", "createSecureToken", "createSubscription", "deleteSecureToken", "getSecureToken", "listSecureTokens", "payment", "updateSecureToken" ] } }, { "route": "/api/resources/subscriptions", "type": "guide", "title": "Subscriptions", "description": "Reference for the subscription endpoints, covering how to create, retrieve, list, update, deactivate, reactivate, and manually collect a repeat payment from a customer.", "headings": [ "Retrieve the details of the subscription", "Update the subscription", "Stop the subscription", "Manually collect a payment for the subscription" ], "plainText": "Important: Before you can use the Subscriptions endpoints, you need to integrate with the Payment Plans endpoints and the Secure Tokens endpoints. Use our Subscriptions endpoints to take repeat payments from customers. Integrate with our Create Subscription method to assign a customer to a payment plan and take repeat payments. The Create Subscription request contains the following details: ID of the payment plan that the merchant wants to use. Secure token that represents the customer's payment details. (Optional) Adjustments that override details of the payment plan. When you create a subscription, you also need to provide a subscriptionId, which you can use to complete the following actions: Retrieve the details of the subscription Integrate with our Retrieve Subscription method to view details of the subscription, including the amount for each payment, start date, and payment schedule. Integrate with our List Subscription method to return a paginated list of subscriptions that meet specific query parameters. Update the subscription Integrate with our Update Subscription method to update the details of the subscription, for example, increase the amount for each payment. Stop the subscription Integrate with our Deactivate Subscription method to stop taking payments from the customer. If you want to start taking payments again, integrate with our Re-activate Subscription method. Manually collect a payment for the subscription Integrate with the Pay Manual Subscription method to manually collect a payment.", "refs": { "workflowIds": [], "operationIds": [ "createSecureToken", "createSubscription", "deactivateSubscription", "getSubscription", "listSubscriptions", "paySubscription", "reactivateSubscription", "updateSubscription" ] } }, { "route": "/api/retrieve-device-configuration", "type": "reference", "title": "Retrieve a device configuration", "description": "GET /processing-terminals/{processingTerminalId}/device-configurations/{model}", "headings": [], "plainText": "Use this method to retrieve configuration details for a device associated with a processing terminal. Our gateway returns the following details about the configuration: Supported features Applications Certificates and revoked certificates Visual assets", "refs": { "workflowIds": [ "configure-a-device" ], "operationIds": [ "retrieveDeviceConfiguration" ] } }, { "route": "/api/retrieve-payment-link", "type": "reference", "title": "Retrieve payment link", "description": "GET /payment-links/{paymentLinkId}", "headings": [], "plainText": "Use this method to retrieve information about a payment link. To retrieve a payment link, you need its paymentLinkId. Our gateway returned the paymentLinkId in the response of the Create Payment Link method. Note: If you don't have the paymentLinkId, use our List Payment Links method to search for the payment link. Our gateway returns the following information about the payment link: type - Indicates whether the link can be used only once or if it can be used multiple times. authType - Indicates whether the transaction is a sale or a pre-authorization. paymentMethods - Indicates the payment method that the merchant accepts. charge - Indicates whether the merchant or the customer enters the amount for the transaction. status - Indicates if the payment link is active.", "refs": { "workflowIds": [ "collect-with-payment-link" ], "operationIds": [ "retrievePaymentLink" ] } }, { "route": "/api/retrieve-processing-account-pricing", "type": "reference", "title": "Retrieve processing account pricing agreement", "description": "GET /processing-accounts/{processingAccountId}/pricing", "headings": [], "plainText": "Use this method to retrieve the pricing agreement that we apply to a processing account. To retrieve the pricing agreement of a processing account, you need the processingAccountId. Our gateway returned the processingAccountId in the response to the Create Merchant Platform method and Create Processing Account method. Note: If you don't have the processingAccountId, use our List Merchant Platform’s Processing Accounts method to search for the processing account. Our gateway returns the following information about the pricing agreement that we apply to the processing account: Base fees, including the annual fee and the fees for each chargeback and retrieval. Processor fees, including the fees that we apply for processing card and ACH payments. Gateway fees, including the setup fee and the fees for each transaction. Service fees, including the fee that we apply if the merchant has signed up to a Hardware Advantage Plan.", "refs": { "workflowIds": [ "review-merchant-hierarchy" ], "operationIds": [ "retrieveProcessingAccountPricing" ] } }, { "route": "/api/retrieve-signature", "type": "reference", "title": "Retrieve signature", "description": "GET /signatures/{signatureId}", "headings": [], "plainText": "Use this method to retrieve a signature that a payment device captured using Payroc Cloud. Our gateway returns the following information about the signature: Image of the signature Format of the image Date that the device captured the image", "refs": { "workflowIds": [ "capture-signature-on-a-device" ], "operationIds": [ "retrieveSignature" ] } }, { "route": "/api/reverse-bank-transfer-payment", "type": "reference", "title": "Reverse payment", "description": "POST /bank-transfer-payments/{paymentId}/reverse", "headings": [], "plainText": "Use this method to cancel a bank transfer payment in an open batch. This is also known as voiding a payment. To cancel a bank transfer payment, you need its paymentId. Our gateway returned the paymentId in the response of the Create Payment method. Note: If you don't have the paymentId, use our List Payments method to search for the bank transfer payment. If your request is successful, our gateway removes the bank transfer payment from the merchant’s open batch and no funds are taken from the customer's bank account.", "refs": { "workflowIds": [ "reverse-a-bank-transfer-payment" ], "operationIds": [ "reverseBankTransferPayment" ] } }, { "route": "/api/reverse-bank-transfer-refund", "type": "reference", "title": "Reverse refund", "description": "POST /bank-transfer-refunds/{refundId}/reverse", "headings": [], "plainText": "Use this method to cancel a bank transfer refund in an open batch. To cancel a refund, you need its refundId. Our gateway returned the refundId in the response of the Refund Payment or Create Refund method. Note: If you don’t have the refundId, use our List Refunds method to search for the refund. If your request is successful, the gateway removes the refund from the merchant’s open batch, and no funds are returned to the cardholder’s account.", "refs": { "workflowIds": [ "reverse-a-bank-transfer-refund" ], "operationIds": [ "reverseBankTransferRefund" ] } }, { "route": "/api/reverse-payment", "type": "reference", "title": "Reverse payment", "description": "POST /payments/{paymentId}/reverse", "headings": [], "plainText": "Use this method to cancel or to partially cancel a payment in an open batch. This is also known as voiding a payment. To cancel a payment, you need its paymentId. Our gateway returned the paymentId in the response of the Create Payment method. Note: If you don't have the paymentId, use our List Payments method to search for the payment. If your request is successful, our gateway removes the payment from the merchant's open batch and no funds are taken from the cardholder's account.", "refs": { "workflowIds": [ "pay-with-single-use-token", "reverse-a-card-payment" ], "operationIds": [ "reversePayment" ] } }, { "route": "/api/reverse-refund", "type": "reference", "title": "Reverse refund", "description": "POST /refunds/{refundId}/reverse", "headings": [], "plainText": "Use this method to cancel a refund in an open batch. To cancel a refund, you need its refundId. Our gateway returned the refundId in the response of the Refund Payment or Create Refund method. Note: If you don’t have the refundId, use our List Refunds method to search for the refund. If your request is successful, the gateway removes the refund from the merchant’s open batch and no funds are returned to the cardholder’s account.", "refs": { "workflowIds": [ "reverse-a-refund" ], "operationIds": [ "reverseRefund" ] } }, { "route": "/api/search-devices", "type": "reference", "title": "Search devices", "description": "GET /devices", "headings": [], "plainText": "Use this method to return a paginated list of devices associated with a merchant's API key or an ISV's API key. Use the query parameters to filter the list of results that we return, for example, to search for devices by their model. Our gateway returns the following information about each device in the list: Unique identifier that we assigned to the device. Serial number of the device. Key serial identifier (KSI) of the device. Device model or type of device. Date that our gateway added the device to our systems. Information about the last transaction that the device processed.", "refs": { "workflowIds": [ "run-a-sale-on-a-device" ], "operationIds": [ "searchDevices" ] } }, { "route": "/api/send-payment-instruction", "type": "reference", "title": "Submit payment instruction", "description": "POST /devices/{serialNumber}/payment-instructions", "headings": [], "plainText": "Use this method to submit an instruction request to initiate a sale on a payment device. In the request, include the order amount and currency. When you send a successful request, our gateway returns information about the payment instruction and a paymentInstructionId, which you need for the following methods: Retrieve payment instruction - View the details of the payment instruction. Cancel payment instruction - Cancel the payment instruction.", "refs": { "workflowIds": [ "run-a-sale-on-a-device" ], "operationIds": [ "sendPaymentInstruction" ] } }, { "route": "/api/send-refund-instruction", "type": "reference", "title": "Submit refund instruction", "description": "POST /devices/{serialNumber}/refund-instructions", "headings": [], "plainText": "Use this method to submit an instruction request to initiate a refund on a payment device. In the request, include the refund amount and currency. If the request is successful, our gateway returns information about the refund instruction and a refundInstructionId, which you need for the following methods: Retrieve refund instruction - View the details of the refund instruction. Cancel refund instruction - Cancel the refund instruction.", "refs": { "workflowIds": [ "refund-on-a-device" ], "operationIds": [ "sendRefundInstruction" ] } }, { "route": "/api/send-signature-instruction", "type": "reference", "title": "Submit signature instruction", "description": "POST /devices/{serialNumber}/signature-instructions", "headings": [], "plainText": "Use this method to submit an instruction to capture a customer's signature on a payment device. Our gateway returns information about the signature instruction and a signatureInstructionId, which you need for the following methods: Retrieve signature instruction - View the details of the signature instruction. Cancel signature instruction - Cancel the signature instruction.", "refs": { "workflowIds": [ "capture-signature-on-a-device" ], "operationIds": [ "sendSignatureInstruction" ] } }, { "route": "/api/share-payment-link", "type": "reference", "title": "Share payment link", "description": "POST /payment-links/{paymentLinkId}/sharing-events", "headings": [], "plainText": "Use this method to email a payment link to a customer. To email a payment link, you need its paymentLinkId. Our gateway returned the paymentLinkId in the response of the Create Payment Link method. Note: If you don't have the paymentLinkId, use our List Payment Links method to search for the payment link. In the request, you must provide the recipient's name and email address. In the response, our gateway returns a sharingEventId, which you can use to List Payment Link Sharing Events .", "refs": { "workflowIds": [ "collect-with-payment-link" ], "operationIds": [ "sharePaymentLink" ] } }, { "route": "/api/unreferenced-refund", "type": "reference", "title": "Create unreferenced refund", "description": "POST /refunds", "headings": [], "plainText": "Use this method to create an unreferenced refund. An unreferenced refund is a refund that isn't linked to a payment. Note: If you have the paymentId of the payment you want to refund, use our Refund Payment method. If you use our Refund Payment method, our gateway sends the refund amount to the customer's original payment method and links the refund to the payment. In the request, you must provide the customer's payment details and the refund amount. In the response, our gateway returns information about the refund and a refundId, which you need for the following methods: Retrieve refund - View the details of the refund. Adjust refund - Update the details of the refund. Reverse refund - Cancel the refund if it's in an open batch.", "refs": { "workflowIds": [ "run-unreferenced-card-refund" ], "operationIds": [ "unreferencedRefund" ] } }, { "route": "/api/update-contact", "type": "reference", "title": "Update contact", "description": "PUT /contacts/{contactId}", "headings": [], "plainText": "Use this method to update a contact of a processing account. To update a contact, you need its contactId. Our gateway returned the contactId in the response of the Create Processing Account method. Note: If you don't have the contactId, use our List Contacts method to search for the contact. You can update the following details about a contact: First name and last name. Contact details, including their phone number or mobile number. Identification details, including their identification type and number. Role within the business, for example, if they are a manager.", "refs": { "workflowIds": [ "update-a-contact" ], "operationIds": [ "updateContact" ] } }, { "route": "/api/update-event-subscription", "type": "reference", "title": "Update event subscription", "description": "PUT /event-subscriptions/{subscriptionId}", "headings": [], "plainText": "Use this method to update the details of an event subscription. To update an event subscription, you need its subscriptionId. Our gateway returned the subscriptionId in the response of the Create Event Subscription method. Note: If you don’t have the subscriptionId, use our List Event Subscriptions method to search for the event subscription. You can update the following details about an event subscription: Status of the event subscription. Events that you have subscribed to. For a list of events that you can subscribe to, go to Events list . Information about how we contact you when an event occurs.", "refs": { "workflowIds": [ "update-an-event-subscription" ], "operationIds": [ "updateEventSubscription" ] } }, { "route": "/api/update-funding-account", "type": "reference", "title": "Update funding account", "description": "PUT /funding-accounts/{fundingAccountId}", "headings": [], "plainText": "Important: You can't update the details of a funding account that is associated with a processing account. Use this method to update the details of a funding account that is associated with a funding recipient. To update a funding account, you need its fundingAccountId. Our gateway returned the fundingAccountId when you created the funding account. Note: If you don’t have the fundingAccountId, use our List Funding Accounts method to search for the funding account. You can update the following details about the funding account: Account type. Account holder's name. ACH information for the account.", "refs": { "workflowIds": [ "update-a-funding-account" ], "operationIds": [ "updateFundingAccount" ] } }, { "route": "/api/update-funding-recipient", "type": "reference", "title": "Update funding recipient", "description": "PUT /funding-recipients/{recipientId}", "headings": [], "plainText": "Use this method to update the details of a funding recipient. If a request contains significant changes, we might need to re-approve the funding recipient. To update a funding recipient, you need it's recipientId. Our gateway returned the recipientId in the response of the Create Funding Recipient method. Note : If you don't have the recipientId, use our List Funding Recipients method to search for the funding recipient. You can update the following details of a funding recipient: Doing Business As (DBA) name Tax ID and charity ID Address and contact methods", "refs": { "workflowIds": [ "update-a-funding-recipient" ], "operationIds": [ "updateFundingRecipient" ] } }, { "route": "/api/update-instructions", "type": "reference", "title": "Update funding instruction", "description": "PUT /funding-instructions/{instructionId}", "headings": [], "plainText": "Important: You can update a funding instruction only if its status is accepted . To view the status of a funding instruction, use our Retrieve Funding Instruction method. Use this method to update the details of a funding instruction. To update a funding instruction, you need its instructionId. Our gateway returned the instructionId in the response of the Create Funding Instruction method. Note: If you don't have the fundingInstructionId, use our List Funding Instructions method to search for the funding instruction. You can modify the following information for the funding instruction: Merchant ID (MID) of the merchant whose funding balance you want to distribute. Funding account that you want to send funds to. Amount that you want to send to the funding account.", "refs": { "workflowIds": [ "update-a-funding-instruction" ], "operationIds": [ "updateInstructions" ] } }, { "route": "/api/update-owner", "type": "reference", "title": "Update owner", "description": "PUT /owners/{ownerId}", "headings": [], "plainText": "Important: You can't update the details of an owner of a processing account. Use this method to update the details of an owner associated with a funding recipient. To update an owner, you need their ownerId. Our gateway returned the ownerId in the response of the Create Funding Recipient method and the Create Funding Recipient Owner method. Note: If you don't have the ownerId, use the List Funding Recipient Owners method, the Retrieve Funding Recipient method, or the List Funding Recipients method to search for the funding recipient owner. You can update the following details about an owner: Personal details, including their name, date of birth, and address. Identification details, including their identification type and number. Contact details, including their email address. Relationship to the business, including whether they are a control prong.", "refs": { "workflowIds": [ "update-an-owner" ], "operationIds": [ "updateOwner" ] } }, { "route": "/api/update-payment-link", "type": "reference", "title": "Partially update payment link", "description": "PATCH /payment-links/{paymentLinkId}", "headings": [], "plainText": "Use this method to partially update a payment link. Structure your request to follow the RFC 6902 standard. To update a payment link, you need its paymentLinkId, which we sent you in the response of the Create Payment Link method. Note: If you don't have the paymentLinkId, use our List Payment Links method to search for the payment link. You can update the following properties of a multi-use link: expiresOn parameter - Expiration date of the link. customLabels object - Label for the payment button. credentialOnFile object - Settings for saving the customer's payment details. You can update the following properties of a single-use link: expiresOn parameter - Expiration date of the link. authType parameter - Transaction type of the payment link. amount parameter - Total amount of the transaction. currency parameter - Currency of the transaction. description parameter - Brief description of the transaction. customLabels object - Label for the payment button. credentialOnFile object - Settings for saving the customer's payment details. Note: When a merchant updates a single-use link, we update the payment URL and HTML code in the assets object. The customer can't use the original link to make a payment.", "refs": { "workflowIds": [ "collect-with-payment-link" ], "operationIds": [ "updatePaymentLink" ] } }, { "route": "/api/update-payment-plan", "type": "reference", "title": "Partially update payment plan", "description": "PATCH /processing-terminals/{processingTerminalId}/payment-plans/{paymentPlanId}", "headings": [], "plainText": "Use this method to partially update a payment plan. Structure your request to follow the RFC 6902 standard. To update a payment plan, you need its paymentPlanId, which you sent in the request of the Create Payment Plan method. Note: If you don't have the paymentPlanId, use our List Payment Plans method to search for the payment plan. You can update all of the properties of the payment plan except for the paymentPlanId. The value you sent for the onUpdate parameter when you created the payment plan indicates what happens to the associated subscriptions when you update the plan: update - Our gateway updates the subscriptions associated with the payment plan. continue - Our gateway doesn't update the subscriptions associated with the payment plan.", "refs": { "workflowIds": [ "update-a-payment-plan" ], "operationIds": [ "updatePaymentPlan" ] } }, { "route": "/api/update-pricing-intent", "type": "reference", "title": "Update pricing intent", "description": "PUT /pricing-intents/{pricingIntentId}", "headings": [], "plainText": "Use this method to update the details of a pricing intent. If you update a pricing intent, it won't affect merchant that you've previously onboarded. To update a pricing intent, you need its pricingIntentId. Our gateway returned the pricingIntentId in the response of the Create Pricing Intent method. Note: If you don't have the pricingIntentId, use our List Pricing Intents method to search for the pricing intent. You can update the following details about a pricing intent: Fees, including the base fees, processor fees, and gateway fees. Custom name for the pricing intent. Additional services that merchants can sign up for.", "refs": { "workflowIds": [ "replace-a-pricing-intent" ], "operationIds": [ "updatePricingIntent" ] } }, { "route": "/api/update-secure-token", "type": "reference", "title": "Partially update secure token", "description": "PATCH /processing-terminals/{processingTerminalId}/secure-tokens/{secureTokenId}", "headings": [], "plainText": "Use this method to partially update a secure token. Structure your request to follow the RFC 6902 standard. To update a secure token, you need its secureTokenId, which you sent in the request of the Create Secure Token method. Note: If you don't have the secureTokenId, use our List Secure Tokens method to search for the payment. You can update all of the properties of the secure token, except the following: processingTerminalId type token status source/Card type cardNumber cardType currency debit surcharging source/ACH account accountNumber routingNumber source/PAD account type accountNumber transitNumber", "refs": { "workflowIds": [ "update-a-saved-payment-method" ], "operationIds": [ "updateSecureToken" ] } }, { "route": "/api/update-subscription", "type": "reference", "title": "Partially update subscription", "description": "PATCH /processing-terminals/{processingTerminalId}/subscriptions/{subscriptionId}", "headings": [], "plainText": "Use this method to partially update a subscription. Structure your request to follow the RFC 6902 standard. To update a subscription, you need its subscriptionId, which you sent in the request of the Create subscription method. Note: If you don't have the subscriptionId, use our List subscriptions method to search for the payment. You can update all of the properties of the subscription except for the following: Can't delete recurringOrder description name Can't perform any PATCH operation currentState type frequency paymentPlan", "refs": { "workflowIds": [ "manage-subscriptions" ], "operationIds": [ "updateSubscription" ] } }, { "route": "/api/verify-bank-account", "type": "reference", "title": "Verify bank account", "description": "POST /bank-accounts/verify", "headings": [], "plainText": "Use this method to verify a customer's bank account details. In the request, send the customer's bank account details. Our gateway can verify the following types of bank details: Automated Clearing House (ACH) details Pre-Authorized Debit (PAD) details In the response, our gateway indicates if the account details are valid and if you should use them in follow-on actions.", "refs": { "workflowIds": [ "verify-a-bank-account" ], "operationIds": [ "verifyBankAccount" ] } }, { "route": "/api/verify-card", "type": "reference", "title": "Verify card", "description": "POST /cards/verify", "headings": [], "plainText": "Use this method to verify a customer’s card details. In the request, send the customer’s card details. In the response, our gateway indicates if the card details are valid and if you should use them in follow-on actions.", "refs": { "workflowIds": [ "verify-a-card" ], "operationIds": [ "verifyCard" ] } }, { "route": "/api/versioning", "type": "guide", "title": "Versioning", "description": "Explains the Payroc API agile versioning strategy, including how backward compatibility is maintained and how version numbers are incremented and specified in request URLs.", "headings": [ "How we implement agile versioning" ], "plainText": "We apply an agile versioning strategy to our API. This means that when we update our API, we maintain backward compatibility for as long as possible. We increment the API version only when changes break backward compatibility. How we implement agile versioning We specify the version number of the API in the URL of the resource, directly before the category or feature name. For example, https://api.payroc.com/v1/funding-accounts. When we release a major update, we update the version number of the API to the next whole number. Important: Use HTTPS for all requests to the Payroc API. We reject all HTTP requests, and all requests that are not properly authenticated.", "refs": { "workflowIds": [], "operationIds": [] } }, { "route": "/guides", "type": "guide", "title": "Guides", "description": "Build and test your Payroc integration.", "headings": [ "Getting started", "API keys", "Payments", "Payroc Cloud", "Testing" ], "plainText": "Getting started Set up and test your first integration. Browse guides → API keys Create and manage Payroc App API keys. Browse guides → Payments Integrate hosted checkout, Hosted Fields and digital wallets. Browse guides → Payroc Cloud Connect in-person payment devices to your integration. Browse guides → Testing Send requests to the Payroc Cloud Simulator. Browse guides →", "refs": { "workflowIds": [], "operationIds": [] } }, { "route": "/guides/api-keys", "type": "guide", "title": "API keys", "description": "Create and manage Payroc App API keys.", "headings": [], "plainText": "Create and manage Payroc App API keys. Generate a Payroc App API key View a Payroc App API key Change the settings of a Payroc App API key Deactivate a Payroc App API key Reactivate a Payroc App API key", "refs": { "workflowIds": [], "operationIds": [] } }, { "route": "/guides/api-keys/change-the-settings-of-a-payroc-app-api-key", "type": "guide", "title": "Change the settings of a Payroc App API key", "description": "Explains how to update the alias, notification email, API permissions, and processing terminals of a Payroc App API key using the Self-Care Portal.", "headings": [], "plainText": "You can change the settings of a Payroc App API key in the Self-Care Portal. Sign in to https://payments.payroc.com/merchant/selfcare. On the side menu, select Settings, and then select API Keys. Select the API key that you want to update. Note: You can use the search function to search by the Key Alias that you assigned to the key when you created it. In the General Setup tab, update the following settings: Key Alias - Update the name of the API key. Notification Email - Update the email address that we send notifications to when we create, deactivate, or reactivate the API key. API Permissions - Select which APIs the API key can access and its permission levels. Select SAVE. In the Processing Terminals tab, select which processing terminals the API key applies to. Select SAVE.", "refs": { "workflowIds": [], "operationIds": [] } }, { "route": "/guides/api-keys/deactivate-a-payroc-app-api-key", "type": "guide", "title": "Deactivate a Payroc App API key", "description": "Explains how to deactivate a Payroc App API key in the Self-Care Portal, preventing its use without permanently deleting it.", "headings": [], "plainText": "You can deactivate a Payroc App API key in the Self-Care Portal. After you deactivate a Payroc App API key, you can still view its details, but you can't use it unless you reactivate it. To deactivate a Payroc App API key, complete the following steps: Sign in to https://payments.payroc.com/merchant/selfcare. On the side menu, select Settings, and then select API Keys. Locate the API key that you want to deactivate. Note: You can use the search function to search by the Key Alias that you assigned to the key when you created it. From the Action column, select , and then select Revoke. Select OK.", "refs": { "workflowIds": [], "operationIds": [] } }, { "route": "/guides/api-keys/generate-a-payroc-app-api-key", "type": "guide", "title": "Generate a Payroc App API key", "description": "Shows how to generate and view a Payroc App API key in the Self-Care Portal to authenticate with the Payroc Cloud Simulator.", "headings": [ "Generate a Payroc App API key", "View the Payroc App API key" ], "plainText": "To use the Payroc Cloud Simulator, you need a Payroc App API key, which you can generate and view in the Self-Care Portal. Note: If you don't have access to the Self-Care Portal, contact our Integrations Team at integrationsupport@payroc.com. Generate a Payroc App API key Sign in to https://payments.payroc.com/merchant/selfcare. On the side menu, select Settings, and then select API Keys. Select NEW API KEY. In the Key Alias box, enter the name of the API key. In the Notification Email box, enter your email address. We send notifications to this email address when we create, revoke, or reactivate the API key. In the API Permissions section, select the following checkboxes:Account API – Access the merchant gateway account. Customer API – Access customer details, for example, secure tokens and subscriptions. Transaction API – Run card transactions. Bank Transfer API – Run bank transfer transactions. Reporting API – Access to reporting data. For each API that you selected, select the dropdown menu, and then select Full Access. Select SAVE. Select the processing terminals that the key applies to. Select SAVE. View the Payroc App API key On the side menu, select Settings, and then select API Keys. Locate the API key that you want to view. Note: You can use the search function to search by the Key Alias that you assigned to the key when you created it. From the Action column, select , and then select View Authentication Key. Enter the password for your Self-Care Portal account. View and copy the key. Note: You can use the Self-Care Portal to update, deactivate, and reactivate the Payroc App API keys. For more information about how to manage API keys, go to API keys.", "refs": { "workflowIds": [], "operationIds": [] } }, { "route": "/guides/api-keys/reactivate-a-payroc-app-api-key", "type": "guide", "title": "Reactivate a Payroc App API key", "description": "Explains how to reactivate a previously deactivated Payroc App API key using the Self-Care Portal.", "headings": [], "plainText": "You can reactivate a Payroc App API key that you previously deactivated in the Self-Care Portal. To reactivate a Payroc App API key, complete the following steps: Sign in to https://payments.payroc.com/merchant/selfcare. On the side menu, select Settings, and then select API Keys. To view the Payroc App API keys that you've deactivated, select the Revoked tab. API Keys Revoked Tab Locate the API key that you want to reactivate. Note: You can use the search function to search by the Key Alias that you assigned to the key when you created it. From the Action column, select , and then select Authorize. Select OK.", "refs": { "workflowIds": [], "operationIds": [] } }, { "route": "/guides/api-keys/view-a-payroc-app-api-key", "type": "guide", "title": "View a Payroc App API key", "description": "Explains how to locate and copy a Payroc App API key from the Self-Care Portal.", "headings": [], "plainText": "You can view a Payroc App API key in the Self-Care Portal. Note: If you don't have access to the Self-Care Portal, contact our Integrations Team at integrationsupport@payroc.com. To view a Payroc App API key, complete the following steps: Sign in to https://payments.payroc.com/merchant/selfcare. On the side menu, select Settings, and then select API Keys. Locate the API key that you want to view. Note: You can use the search function to search by the Key Alias that you assigned to the key when you created it. From the Action column, select , and then select View Authentication Key. Enter the password for your Self-Care Portal account. View and copy the key.", "refs": { "workflowIds": [], "operationIds": [] } }, { "route": "/guides/boarding", "type": "guide", "title": "Board a merchant", "description": "Board a merchant by creating a merchant platform with processing accounts, owners, contacts, and a terminal order.", "headings": [ "Relationship between the boarding resources", "Example", "Pricing", "Your integration journey", "Guides", "Create a pricing intent", "Create a merchant platform", "Add a processing account to a merchant platform", "Create a terminal order", "Add an attachment to a processing account" ], "plainText": "Prerequisites: Authentication To board a merchant with Payroc, you need to create the following resources: Merchant platform – The business and its legal information, its owners, and its processing accounts. Processing accounts – Each merchant platform must include one or more processing accounts that run transactions. Owners – Each processing account must include one or more owners. You must assign a control prong who is responsible for their merchant account. Contacts – Each processing account can include additional contacts. They are individuals we can contact about the processing account, for example, a store manager. Terminal orders – Each processing account can order one or more terminals to run transactions. Note: When you create a merchant platform, we recommend that you add all the business's processing accounts. If the business expands after you board a merchant, you can add additional processing accounts and their contacts. Relationship between the boarding resources The merchant platform is the main boarding resource and includes all the information about the business, including its legal information, processing accounts, owners, and contacts. The following diagram shows the relationship between the boarding resources: flowchart TD MP[\"Merchant platform\"]:::blue PA[\"Processing account\"]:::green TO[\"Terminal order\"]:::neutral OW[\"Owner\"]:::neutral CO[\"Contact\"]:::neutral MP --- PA PA -.- TO PA --- OW & CO classDef blue fill:#0051C2,stroke:#001D4E,color:#FFFFFF classDef green fill:#00E0B8,stroke:#001D4E,color:#001D4E classDef neutral fill:#E5E5E5,stroke:#636363,color:#001D4E Example The following example shows a merchant platform with two processing accounts: Springfield processing account has one owner and two contacts. Boston processing account has two owners and one contact. flowchart TD RMP[\"Rocfood merchant platform\"]:::blue SPA[\"Springfield processing account\"]:::green BPA[\"Boston processing account\"]:::green STO[\"Terminal order\"]:::neutral SOW[\"Owne", "refs": { "workflowIds": [], "operationIds": [] } }, { "route": "/guides/boarding/add-attachment-to-processing-account", "type": "guide", "title": "Add an attachment to a processing account", "description": "Upload a document to a processing account by sending a POST request to the Processing Accounts attachments endpoint, then optionally check the upload status via the Attachments endpoint.", "headings": [ "Integration steps", "Before you begin", "Step 1. Upload an attachment", "Request parameters", "Schema (request.body)", "Example request", "Request", "Response fields", "Schema (response.body)", "Example response", "Response (201)", "Step 2. (Optional) Check the upload status of the attachment", "Example request", "Request", "Response fields", "Schema (response.body)", "Example response", "Response (200)" ], "plainText": "Prerequisites: Authentication You can use the attachments feature of our API to add a document to a processing account to support a merchant's application, for example, questionnaires, banking evidence, and personal identification. You can add only one attachment in each request to our API, and each attachment must be an uncompressed file under 50 MB in one of the following formats: .bmp, .csv, .doc, .docx, .gif, .htm, .html, .jpg, .jpeg, .msg, .pdf, .png, .ppt, .pptx, .tif, .tiff, .txt, .xls, .xlsx After we receive your request, we upload the document and attach it to the processing account. You can use our API to check the upload status of the document and to view information about the document. Integration steps Upload an attachment. (Optional) Check the upload status of the attachment. Before you begin Authenticate your requests before making API calls. If your request fails, see Errors. Important: This endpoint accepts a file upload. Set the value of the Content-Type header to multipart/form-data instead of application/json. Step 1. Upload an attachment To upload an attachment, send a POST request to our Processing Accounts endpoint. Environment URL Test https://api.uat.payroc.com/v1/processing-accounts/{processingAccountId}/attachments Production https://api.payroc.com/v1/processing-accounts/{processingAccountId}/attachments Request parameters To create the body of your request, use the following parameters: Schema (request.body) Request body schema for POST /processing-accounts/{processingAccountId}/attachments Example request Request POST https://api.payroc.com/v1/processing-accounts/{processingAccountId}/attachments curl -X POST https://api.payroc.com/v1/processing-accounts/38765/attachments \\ -H \"Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324\" \\ -H \"Authorization: Bearer \" \\ -H \"Content-Type: multipart/form-data\" \\ -F attachment='{ \"type\": \"personalIdentification\", \"description\": \"Passport as identification for lease agreement\", \"metadata\": {", "refs": { "workflowIds": [], "operationIds": [ "createProcessingAccountAttachment", "getAttachment" ] } }, { "route": "/guides/boarding/merchant-platform", "type": "guide", "title": "Create a merchant platform", "description": "Create a merchant platform by sending a POST request to the merchant-platforms endpoint with the business's legal information, then optionally send a reminder to prompt the merchant's signature.", "headings": [ "Integration steps", "Before you begin", "Step 1. Create a merchant platform", "Request parameters", "Schema (request.body)", "Example request", "Request", "Response fields", "Schema (response.body)", "Example response", "Response (201)", "Step 2. (Optional) Create a reminder", "Request parameters", "Schema (request.body)", "Example request", "Request", "Response fields", "Schema (response.body)", "Example response", "Response (201)" ], "plainText": "Prerequisites: Authentication An AI skill is available for this guide, get it on the Skills Marketplace (GitHub). A merchant platform contains all the details of a merchant's business. When you create a merchant platform, you provide the legal information about the business, which includes the unique tax ID, the legal business name, and the type of organization. We recommend that you also add all processing accounts that the merchant's business requires. For each processing account, include the following details: Business details including the Merchant Category Code (MCC) , Doing Business As (DBA) name, and address of the business. Owners' details including their names, addresses, and contact details. You must assign a control prong who is responsible for their account. Processing details including estimated average transaction amounts and monthly processing amounts. Pricing and funding details including pricing agreements and funding accounts for the processing account. Note: If the merchant’s business expands, you can add more processing accounts. Integration steps Step 1. Create a merchant platform Step 2. (Optional) Create a reminder Before you begin Authenticate your requests before making API calls. If your request fails, see Errors. Step 1. Create a merchant platform To create a merchant platform, send a POST request to our merchant platform endpoint. Environment URL Test https://api.uat.payroc.com/v1/merchant-platforms Production https://api.payroc.com/v1/merchant-platforms Request parameters To create the body of your request, use the following parameters: Schema (request.body) Request body schema for POST /merchant-platforms Example request Request POST https://api.payroc.com/v1/merchant-platforms Create merchant platform curl -X POST https://api.payroc.com/v1/merchant-platforms \\ -H \"Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324\" \\ -H \"Authorization: Bearer \" \\ -H \"Content-Type: application/json\" \\ -d '{ \"business\": { \"name\": \"Example Corp\"", "refs": { "workflowIds": [], "operationIds": [ "createMerchant", "createReminder" ] } }, { "route": "/guides/boarding/order-a-terminal", "type": "guide", "title": "Order a terminal", "description": "Order one or more terminals for a processing account by sending a POST request to the processing accounts terminal-orders endpoint with training, shipping, and solution details.", "headings": [ "Integration steps", "Before you begin", "Create a terminal order", "Request parameters", "Schema (request.body)", "Example request", "Request", "Response fields", "Schema (response.body)", "Example response", "Response (201)" ], "plainText": "Prerequisites: Authentication Important: These documents are an early draft and are subject to change. To order a terminal, you need the processingAccountId of the account you want to order the terminal for. To get the processingAccountId, go to Retrieve Merchant Platform. To order one or more terminals for a processing account, provide the following information: Training provider who will train the merchant to use the solution. Shipping address for hardware devices and peripheral devices. Solution details for each terminal including gateway settings, device settings, and application settings. To receive a notification when we change the status of a terminal order, subscribe to our terminalOrder.status.changed event. For more information about how to subscribe to an event, go to Create a Subscription. Integration steps Create a terminal order. Before you begin Authenticate your requests before making API calls. If your request fails, see Errors. Create a terminal order To order a terminal, send a POST request to our processing accounts endpoint. Environment URL Test https://api.uat.payroc.com/v1/processing-accounts/{processingAccountId}/terminal-orders Production https://api.payroc.com/v1/processing-accounts/{processingAccountId}/terminal-orders Request parameters To create the body of your request, use the following parameters: Schema (request.body) Request body schema for POST /processing-accounts/{processingAccountId}/terminal-orders Example request Request POST https://api.payroc.com/v1/processing-accounts/{processingAccountId}/terminal-orders Terminal order curl -X POST https://api.payroc.com/v1/processing-accounts/38765/terminal-orders \\ -H \"Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324\" \\ -H \"Authorization: Bearer \" \\ -H \"Content-Type: application/json\" \\ -d '{ \"orderItems\": [ { \"type\": \"solution\", \"solutionTemplateId\": \"Roc Services_DX8000\", \"solutionQuantity\": 1, \"deviceCondition\": \"new\", \"solutionSetup\": { \"timezone\": \"America/Chicago\", \"ind", "refs": { "workflowIds": [], "operationIds": [ "createTerminalOrder" ] } }, { "route": "/guides/boarding/pricing-intent", "type": "guide", "title": "Create a pricing intent", "description": "Create a pricing intent by sending a POST request to the Pricing Intents endpoint, defining base fees, processor fees, and gateway fees to use as a reusable template for merchant processing accounts.", "headings": [ "Integration steps", "Before you begin", "Create a pricing intent", "Request parameters", "Schema (request.body)", "Example request", "Request", "Response fields", "Schema (response.body)", "Example response", "Response (201)" ], "plainText": "Prerequisites: Authentication A pricing intent is a template of fees that you apply to processing accounts when you board merchants. You can apply the same pricing intent to all processing accounts that you create or create multiple pricing intents to apply to different processing accounts. A pricing intent can include the following fee types: Base fees: For monthly maintenance, chargebacks, and early contract termination. All pricing intents must include base fees. Processor fees: For card payments and Automated Clearing House (ACH) payments. Processor fees also include the pricing model that you offer to the merchant, for example, RewardPay . Gateway fees: For using our payment gateway. Integration steps Create a pricing intent. Before you begin Authenticate your requests before making API calls. If your request fails, see Errors. Create a pricing intent Send a POST request to our Pricing Intents endpoint: Environment URL Test https://api.uat.payroc.com/v1/pricing-intents Production https://api.payroc.com/v1/pricing-intents Request parameters To create the body of your request, use the following parameters: Schema (request.body) Request body schema for POST /pricing-intents Example request Request POST https://api.payroc.com/v1/pricing-intents Created pricing intent curl -X POST https://api.payroc.com/v1/pricing-intents \\ -H \"Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324\" \\ -H \"Authorization: Bearer \" Created pricing intent import requests url = \"https://api.payroc.com/v1/pricing-intents\" headers = { \"Idempotency-Key\": \"8e03978e-40d5-43e8-bc93-6894a57f9324\", \"Authorization\": \"Bearer \" } response = requests.post(url, headers=headers) print(response.json()) Created pricing intent const url = 'https://api.payroc.com/v1/pricing-intents'; const options = { method: 'POST', headers: { 'Idempotency-Key': '8e03978e-40d5-43e8-bc93-6894a57f9324', Authorization: 'Bearer ' } }; try { const response = await fetch(url, options); const data = await re", "refs": { "workflowIds": [], "operationIds": [ "createPricingIntent" ] } }, { "route": "/guides/boarding/processing-account-create", "type": "guide", "title": "Add a processing account to a merchant platform", "description": "Add a processing account to an existing merchant platform by sending a POST request to the Merchant Platforms endpoint with business, owner, processing, and pricing details.", "headings": [ "Integration steps", "Before you begin", "Step 1. Create a processing account", "Request parameters", "Schema (request.body)", "Example request", "Request", "Response fields", "Schema (response.body)", "Example response", "Response (201)", "Step 2. (Optional) Create a reminder", "Request parameters", "Schema (request.body)", "Example request", "Request", "Response fields", "Schema (response.body)", "Example response", "Response (201)" ], "plainText": "Prerequisites: Authentication · Create a merchant platform Important: You must create a merchant platform before you can add additional processing accounts. Each merchant platform includes one or more processing accounts that run transactions for the business. To create a processing account, you must provide the following types of information: Business details including the Merchant Category Code (MCC), Doing Business As (DBA) name, and address of the business. Owners’ details including their names, addresses, and contact details. You must assign a control prong who is responsible for their account. Processing details including estimated average transaction amounts and monthly processing amounts. Pricing and funding details including pricing agreements and funding accounts for the processing account. Note: You can add more than one processing account in the same request. Integration steps Step 1. Create a processing account Step 2. (Optional) Create a reminder Before you begin Authenticate your requests before making API calls. If your request fails, see Errors. Step 1. Create a processing account Send a POST request with the merchantPlatformId to our Merchant Platform endpoint: Environment URL Test https://api.uat.payroc.com/v1/merchant-platforms/{merchantPlatformId}/processing-accounts Production https://api.payroc.com/v1/merchant-platforms/{merchantPlatformId}/processing-accounts Request parameters To create the body of your request, use the following parameters: Schema (request.body) Request body schema for POST /merchant-platforms/{merchantPlatformId}/processing-accounts Example request Request POST https://api.payroc.com/v1/merchant-platforms/{merchantPlatformId}/processing-accounts Create processing account curl -X POST https://api.payroc.com/v1/merchant-platforms/12345/processing-accounts \\ -H \"Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324\" \\ -H \"Authorization: Bearer \" \\ -H \"Content-Type: application/json\" \\ -d '{ \"doingBusinessAs\": \"Pizza Do", "refs": { "workflowIds": [], "operationIds": [ "createProcessingAccount", "createReminder" ] } }, { "route": "/guides/events", "type": "guide", "title": "Event subscriptions", "description": "Subscribe to account changes and handle webhook notifications sent by our gateway.", "headings": [ "How it works", "Subscribe to events", "Handle event notifications", "Your integration journey", "Guides", "Event notifications" ], "plainText": "Prerequisites: Authentication Event subscriptions are a feature of our API that you can subscribe to so that we notify you about changes to an account, for example, when we change the status of a processing account. Note: For a list of the events that you can subscribe to, go to Events list. How it works The following diagram shows how to subscribe to an event and how to handle an event. sequenceDiagram participant YI as Your integration participant GW as Gateway rect rgba(0, 81, 194, 0.4) Note over YI,GW: Subscribe to events YI->>GW: 1. Create an event subscription Note over GW: 2. Gateway creates the event subscription GW-->>YI: 3. Return a response end rect rgba(0, 224, 184, 0.3) Note over YI,GW: Handle event webhook requests Note over GW: 1. A change on the account triggers an event notification GW->>YI: 2. Send a webhook request Note over YI: 3. Receive the webhook request YI->>GW: 4. Return a 200 response end Subscribe to events Create an event subscription and send it to our gateway. Our gateway creates the event subscription. Our gateway sends you a response to confirm that we have created the subscription. Handle event notifications We make a change to an account and trigger an event notification. Our gateway sends a webhook to your endpoint. Your server returns a 200 response to confirm that you have received the webhook. Your integration journey To add event notifications to your integration, complete the following steps: Create an event subscription with our API. Handle the webhook. Guides Event notifications Add event notifications to your integration.", "refs": { "workflowIds": [], "operationIds": [] } }, { "route": "/guides/events/create-event-subscription", "type": "guide", "title": "Create an event subscription", "description": "Create an event subscription by sending a POST request to the event-subscriptions endpoint to receive webhook notifications when specified events occur.", "headings": [ "Integration steps", "Before you begin", "Step 1. Create an event subscription", "Request parameters", "Schema (request.body)", "Example request", "Request", "Response fields", "Schema (response.body)", "Example response", "Response (201)", "Step 2. Send a 200 response code", "Step 3. Handle the notification content" ], "plainText": "Prerequisites: Authentication To add event notifications to your integration, use our API to create an event subscription and handle the notification that we send by webhook when an event occurs. Important: To receive notifications, your server must be able to handle POST requests. To create an event subscription, send the following information in your request: Event type - The event that you want to subscribe to. You can subscribe to more than one event within the same request. URI - The endpoint that we send notifications to. The endpoint must be publicly available. Secret - A secret that we return in the header of webhook requests to verify that it is a genuine request. Event status - The status of the event subscription. Email address - An email address that we contact if we can't communicate with the endpoint that you provided. Note: For a complete list of events that you can subscribe to, go to Events list. Integration steps Step 1. Create an event subscription Step 2. Send a 200 response code Step 3. Handle the notification content Before you begin Authenticate your requests before making API calls. If your request fails, see Errors. Step 1. Create an event subscription To create an event subscription, send a POST request to our event subscriptions endpoint. Environment URL Test https://api.uat.payroc.com/v1/event-subscriptions Production https://api.payroc.com/v1/event-subscriptions Request parameters To create the body of your request, use the following parameters: Schema (request.body) Request body schema for POST /event-subscriptions Example request Request POST https://api.payroc.com/v1/event-subscriptions Create event subscription curl -X POST https://api.payroc.com/v1/event-subscriptions \\ -H \"Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324\" \\ -H \"Authorization: Bearer \" \\ -H \"Content-Type: application/json\" \\ -d '{ \"enabled\": true, \"eventTypes\": [ \"processingAccount.status.changed\" ], \"notifications\": [ { \"type\": \"webhook\", \"secret\": \"aBc", "refs": { "workflowIds": [], "operationIds": [ "createEventSubscription" ] } }, { "route": "/guides/funding", "type": "guide", "title": "Fund merchants", "description": "Configure funding recipients and instructions.", "headings": [], "plainText": "Configure funding recipients and instructions. Send funds to your merchants Set up a funding recipient", "refs": { "workflowIds": [], "operationIds": [] } }, { "route": "/guides/funding/create-funding-instructions", "type": "guide", "title": "Send funds to your merchants", "description": "Send funds to your merchants by creating a Funding Instruction with a POST request to the Funding Instructions endpoint, optionally checking available balance first via GET /v1/funding-balance.", "headings": [ "Integration steps", "Before you begin", "Step 1. (Optional) Check the available balance", "Schema (request.query)", "Example request", "Request", "Schema (response.body)", "Example response", "Response (200)", "Step 2. Create a funding instruction", "Schema (request.body)", "Example request", "Request", "Schema (response.body)", "Example response", "Response (201)", "Test cases" ], "plainText": "Prerequisites: Authentication Important: Before you begin, make sure that you have read our Getting Started guide, and that you have received your API key. To send funds to your merchants, you need to provide us with instructions about: Funding accounts that we should send the funds to Amount of funds that we should send Before you create your funding instructions, we recommend that you check to make sure you have the funds available to send. Integration steps Step 1. (Optional) Check the available balance. Step 2. Create a funding instruction. Before you begin Authenticate your requests before making API calls. If your request fails, see Errors. Step 1. (Optional) Check the available balance To check the available balance, you need to send a GET request to our Funding Balance endpoint. Environment URL Test https://api.uat.payroc.com/v1/funding-balance Production https://api.payroc.com/v1/funding-balance Schema (request.query) Query parameters for GET /funding-balance Example request Request GET https://api.payroc.com/v1/funding-balance Paginated list of merchant balances curl -G https://api.payroc.com/v1/funding-balance \\ -H \"Authorization: Bearer \" \\ -d after=8516 \\ -d before=2571 \\ -d limit=25 \\ -d merchantId=4525644354 Paginated list of merchant balances import requests url = \"https://api.payroc.com/v1/funding-balance\" querystring = {\"after\":\"8516\",\"before\":\"2571\",\"limit\":\"25\",\"merchantId\":\"4525644354\"} headers = {\"Authorization\": \"Bearer \"} response = requests.get(url, headers=headers, params=querystring) print(response.json()) Paginated list of merchant balances const url = 'https://api.payroc.com/v1/funding-balance?after=8516&before=2571&limit=25&merchantId=4525644354'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } Paginated list of merchant balances package main import ", "refs": { "workflowIds": [], "operationIds": [ "createInstruction", "getFundingBalance" ] } }, { "route": "/guides/funding/create-funding-recipients", "type": "guide", "title": "Set up a funding recipient", "description": "Create a funding recipient by sending a POST request to the Funding Recipients endpoint, enabling third-party entities such as charities to receive funds from your account.", "headings": [ "Integration steps", "Before you begin", "Create your funding recipient", "Schema (request.body)", "Example request", "Request", "Schema (response.body)", "Example response", "Response (201)", "Test cases" ], "plainText": "Prerequisites: Authentication Important: Before you begin, make sure that you have read our Getting Started guide, and that you have received your API key. A funding recipient is an entity that can receive funds using funding instructions. Each funding recipient includes at least one of the following: Funding account: The funding recipient’s bank account. Owner: Individuals that are associated with the funding recipient. You can create funding recipients for third parties that can’t directly process sales. For example, charities. Integration steps Create your funding recipient. Before you begin Authenticate your requests before making API calls. If your request fails, see Errors. Create your funding recipient To create your funding recipient, send a POST request to our Funding Recipients endpoint. Environment URL Test https://api.uat.payroc.com/v1/funding-recipients Production https://api.payroc.com/v1/funding-recipients To create the body of your request, use the following parameters: Schema (request.body) Request body schema for POST /funding-recipients Note: Use our metadata feature to add custom information to your request. Example request Request POST https://api.payroc.com/v1/funding-recipients Create funding recipient curl -X POST https://api.payroc.com/v1/funding-recipients \\ -H \"Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324\" \\ -H \"Authorization: Bearer \" \\ -H \"Content-Type: application/json\" \\ -d '{ \"recipientType\": \"privateCorporation\", \"taxId\": \"12-3456789\", \"doingBusinessAs\": \"Pizza Doe\", \"address\": { \"address1\": \"1 Example Ave.\", \"address2\": \"Example Address Line 2\", \"address3\": \"Example Address Line 3\", \"city\": \"Chicago\", \"country\": \"US\", \"postalCode\": \"60056\", \"state\": \"Illinois\" }, \"contactMethods\": [ { \"type\": \"email\", \"value\": \"jane.doe@example.com\" }, { \"type\": \"phone\", \"value\": \"2025550164\" } ], \"owners\": [ { \"firstName\": \"Jane\", \"lastName\": \"Doe\", \"dateOfBirth\": \"1964-03-22\", \"address\": { \"address1\": \"1 Example Ave.\", \"city\": \"Chi", "refs": { "workflowIds": [], "operationIds": [ "createFundingRecipient" ] } }, { "route": "/guides/getting-started", "type": "guide", "title": "Getting started", "description": "Learn the stages of a Payroc integration, from your discovery call to going live with our API.", "headings": [ "Your integration journey", "Base URL" ], "plainText": "Prerequisites: Authentication To integrate with the Payroc API, you need an API key. Contact our Sales team to set up your account and get started. Your integration journey flowchart LR A[\"Discovery call\"] B[\"Statement of work\"] C[\"Development\"] D[\"Validation\"] E[\"Go live\"] F[\"Ongoing support\"] A --> B --> C --> D --> E --> F \\ Stage What happens Discovery call Our Sales Engineering team discuss your requirements and identify the right solutions for your needs. Statement of work We produce a statement of work that defines the scope of your integration. Development Build against our API using our documentation, guides, and integration support team. Validation Test your integration using our sandboxes and test cases. Go live Go live with monitoring from our team for the first few weeks. Ongoing support Reach out to our Customer Support team at any time after launch. Base URL https://api.payroc.com/", "refs": { "workflowIds": [], "operationIds": [] } }, { "route": "/guides/getting-started/quickstart", "type": "guide", "title": "Quickstart", "description": "Get sandbox credentials and make your first Payroc API call.", "headings": [], "plainText": "Create a sandbox account at developers.payroc.com, generate an API key, and make your first request. Every request needs a fresh Idempotency-Key Send a unique UUID v4 per request; reusing a key replays the original response instead of charging twice. curl https://api.payroc.com/v1/payments \\ -H \"Authorization: Bearer $PAYROC_API_KEY\" \\ -H \"Idempotency-Key: $(uuidgen)\"", "refs": { "workflowIds": [], "operationIds": [] } }, { "route": "/guides/payments", "type": "guide", "title": "Payments", "description": "Explains how to use the Payments endpoints to take card, bank account, and digital wallet payments, and to run refunds and repeat payments", "headings": [ "Run transactions", "Schedule repeat payments", "Save payment details", "Verify payment details", "Run a card sale", "Run a sale with bank account details", "Run a pre-authorization", "Refunds" ], "plainText": "Prerequisites: Authentication To take payments from a card, bank account, or digital wallet, use our Payments endpoints. You can use our Payments endpoints in the following channels: In-person payments – Accept payments on a physical terminal. Online payments – Accept payments through online checkout. MOTO payments – Accept payments by telephone, email, and written request. After you integrate with the Payments endpoints, your merchant can: Run transactions including sales and refunds. Schedule repeat payments. Save the customer’s payment details. Verify that payment details are valid. Run transactions We offer the following transaction types: Sale Pre-authorization and capture Referenced refund and unreferenced refund Reversal When you integrate against the Payments endpoints, you can offer the following features: Currency conversion - Give customers the option to pay in their own currency if the merchant’s currency is different. Offline processing – Accept payments even if the terminal can’t connect to the gateway, for example, if the terminal has an unreliable internet connection. Surcharging – Add a surcharge to the customer’s total price to cover the cost of the merchant’s card processing fees. Tipping – Present tip options to customers at the time of the transaction. Schedule repeat payments Integrate with our payment plans and subscriptions method so that your merchants can offer repeat payments to their customers. This can either be recurring payments with no end date, or a series of installment payments for a fixed period. To set up and manage repeat payments, you can either: Use your own software to manage payments, and our gateway to process them. OR Use our gateway to manage and process payments. Save payment details Using our tokenization solution, the merchant can save a customer’s payment details for future payments, which means a faster checkout. You store the payment details in either our vault or your own vault, and we return a token that a merchan", "refs": { "workflowIds": [], "operationIds": [ "createPaymentPlan", "createSubscription", "verifyBankAccount", "verifyCard" ] } }, { "route": "/guides/payments/add-custom-fields", "type": "guide", "title": "Add custom fields to your integration", "description": "Add merchant-defined custom fields to card payments, bank transfers, refunds, subscriptions, and secure token requests using the customFields object.", "headings": [ "Integration steps", "Before you begin", "Step 1. Contact us to activate custom fields", "Step 2. Create the custom field on the Self Care Portal", "Step 3. (Optional) Set the custom field as a dynamic descriptor", "Enable dynamic descriptors", "Select the custom field to use as the dynamic descriptor", "Step 4. Add the custom field object to your API requests", "Update the value of a custom field", "Payment plans and subscriptions" ], "plainText": "Prerequisites: Authentication To allow merchants to add their own information to transactions, use the custom fields feature of our API. For example, your merchants can use custom fields to add a credit agreement ID, a magazine subscription name, or an internal customer ID. You can also use the custom fields feature to create dynamic descriptors. A dynamic descriptor is text that appears on the customer's statement with the transaction. For more information about dynamic descriptors, go to Dynamic Descriptors. The following resources on our API support the custom fields feature: Card payments and refunds Bank transfer payments and refunds Subscriptions Secure tokens Integration steps Step 1. Contact us to activate custom fields. Step 2. Create the custom field on the merchant's Self Care Portal. Step 3. (Optional) Set the custom field as a dynamic descriptor. Step 4. Add the custom field to your integration. Before you begin Authenticate your requests before making API calls. If your request fails, see Errors. Note: If your request is successful but there is an issue with the custom field, we don’t store the custom field and don’t return it in the response. Step 1. Contact us to activate custom fields Before you can use custom fields, contact our Integrations Team to activate the custom fields feature on your account. To contact our Integrations Team, send an email to integrationsupport@payroc.com. Step 2. Create the custom field on the Self Care Portal Log in to the Self Care Portal or the UAT version of the Self Care Portal. From the side menu, select Settings > Custom Fields > NEW CUSTOM FIELD. Enter the following information about the custom field: Name – The name of the custom field. Type – The data type that the Self Care Portal displays for the custom field. Display order – The position of the custom field on the Self Care Portal. For example, if you set the value for the display order to 3, the custom field appears third in the list of custom fields. Label –", "refs": { "workflowIds": [], "operationIds": [ "bankTransferPayment", "bankTransferUnreferencedRefund", "createPaymentPlan", "createSecureToken", "createSubscription", "paySubscription", "payment", "unreferencedRefund" ] } }, { "route": "/guides/payments/apple-pay", "type": "guide", "title": "Apple Pay®", "description": "Add Apple Pay to your integration so merchants can accept Apple Pay as a payment method for online transactions.", "headings": [ "How it works", "Start an Apple Pay session", "Run a sale", "Your integration journey", "Extend your integration", "Guides", "Add Apple Pay to your integration", "Set up Apple Pay for a merchant", "Add a convenience fee", "Split a payment with multiple merchants" ], "plainText": "Prerequisites: Authentication An AI skill is available for this guide, get it on the Skills Marketplace (GitHub). Apple Pay® is a digital wallet application that Apple customers can use to store payment card details and to pay for goods and services using their Apple devices. When you add Apple Pay to your integration, your merchants can accept Apple Pay as a payment method for online transactions. When a customer uses Apple Pay to make a payment, your integration communicates with the Apple JS API and the Payroc gateway to make the sale. To simplify your integration, our gateway creates and handles the Apple Pay Certificate that you need to run transactions with Apple Pay. How it works sequenceDiagram participant AP as Apple Pay JS API participant YI as Your integration participant GW as Gateway rect rgba(0, 81, 194, 0.4) Note over AP,GW: Start an Apple Pay session Note over YI: 1. Cardholder chooses to pay with Apple Pay YI->>AP: 2. Request the validation URL AP-->>YI: 3. Return the validation URL YI->>GW: 4. Send the validation URL to the Apple Pay sessions API Note over GW: 5. Start the session with Apple and retrieve the merchant session object GW-->>YI: 6. Return the merchant session object end rect rgba(0, 224, 184, 0.3) Note over AP,GW: Run a sale Note over YI: 1. Cardholder confirms their payment method YI->>AP: 2. Send payment request to Apple Note over AP: 3. Apple encrypts the payment details AP-->>YI: 4. Return encrypted payment details YI->>GW: 5. Send the payment details in a payment request GW-->>YI: 6. Return payment response end Start an Apple Pay session Cardholder chooses to pay with Apple Pay, for example, they select the Apple Pay button on the merchant's web page. Your integration requests the validation URL from Apple. Apple returns the validation URL to your integration. Your integration sends a request to our Apple Pay sessions endpoint. The request must include the unique domainId and validation URL. We start an Apple Pay session and get t", "refs": { "workflowIds": [], "operationIds": [] } }, { "route": "/guides/payments/apple-pay/add-a-convenience-fee", "type": "guide", "title": "Add a convenience fee", "description": "Apply a convenience fee to Apple Pay payments by including the multiTokenContexts array in your ApplePayPaymentRequest and sending a single payment request to our gateway.", "headings": [ "How it works", "Before you begin", "Integration steps", "Step 1. Update your Apple Pay integration", "Request parameters", "multiTokenContexts example", "Step 2. Send a payment request" ], "plainText": "Prerequisites: Add Apple Pay to your integration · Set up Apple Pay for a merchant You can extend your Apple Pay integration to add a convenience fee to a payment. How it works You send a request to the Apple Pay JS API that contains the amount for the payment and the amount for the convenience fee. Apple returns a cryptogram after your customer authorizes the total amount. You send a single payment request to our gateway for the total amount of the payment including the convenience fee. Before you begin Integrate with Apple Pay. Set up Apple Pay for the merchant and store their merchant identifier. You must use Apple Pay JS API version 14 or later. Integration steps Update your Apple Pay integration. Send a payment request. Step 1. Update your Apple Pay integration Update your Apple Pay integration to include the multiTokenContexts array with two entries in the ApplePayPaymentRequest. One entry is for the sale amount, and the other entry is for the convenience fee. If your request is successful and the customer authorizes the payment, Apple Pay returns a cryptogram that you need to include in the payment request to our gateway. Request parameters Parameter Description merchantIdentifier Merchant identifier that we assigned when you set up the merchant with Apple Pay. The value is the same for both entries. externalIdentifier ID that our gateway uses to identify the payment and the convenience fee. The value depends on the entry: • For the sale amount, send PRIMARY. • For the convenience fee, send CONVENIENCE_FEE. merchantName Name of the merchant that you set up with Apple Pay. amount Amount for the sale or the convenience fee. multiTokenContexts example \"multiTokenContexts\": [ { \"merchantIdentifier\": \"PMID-2\", \"externalIdentifier\": \"PRIMARY\", \"merchantName\": \"Merchant 1\", \"amount\": \"100.00\" }, { \"merchantIdentifier\": \"PMID-2\", \"externalIdentifier\": \"CONVENIENCE_FEE\", \"merchantName\": \"Merchant 1\", \"amount\": \"2.50\" } ] Step 2. Send a payment request After you receiv", "refs": { "workflowIds": [ "accept-apple-pay" ], "operationIds": [ "payment" ] } }, { "route": "/guides/payments/apple-pay/apple-pay-integrate", "type": "guide", "title": "Add Apple Pay to your integration", "description": "Integrate Apple Pay by starting a merchant session via the Apple Pay sessions endpoint and running a sale via the Payments endpoint with encrypted digital wallet data.", "headings": [ "Integration steps", "Before you begin", "Headers", "Errors", "Step 1. Integrate with the Apple JS API", "Step 2. Integrate with the Payroc API", "Step 2a. Start an Apple Pay session", "Request parameters", "Schema (request.body)", "Example request", "Request", "Response fields", "Schema (response.body)", "Example response", "Response (200)", "Step 2b. Run a sale", "Request parameters", "Schema (request.body)", "Example request", "Request", "Response fields", "Schema (response.body)", "Example response", "Response (201)", "Next steps" ], "plainText": "Prerequisites: Authentication Allow your merchants to accept Apple Pay as a payment method. Integration steps Step 1. Integrate with the Apple Pay JS API. Step 2. Integrate with the Payroc API: Step 2a - Start an Apple Pay session. Step 2b - Run a sale. Before you begin Authenticate your requests before making API calls. If your request fails, see Errors. Headers To create the header of each GET request, you must include the following parameters: Content-Type: Include application/json as the value for this parameter. Authorization: Include your Bearer token in this parameter. curl -H \"Content-Type: application/json\" -H \"Authorization: \" To create the header of each POST request, you must include the following parameters: Content-Type: Include application/json as the value for this parameter. Authorization: Include your Bearer token in this parameter. Idempotency-Key: Include a UUID v4 to make the request idempotent. curl -H \"Content-Type: application/json\" -H \"Authorization: \" -H \"Idempotency-Key: \" Errors If your request is unsuccessful, we return an error. For more information about errors, see Errors. Step 1. Integrate with the Apple JS API To integrate with the Apple Pay JS API, go to https://developer.apple.com/apple-pay/. Your integration with Apple must retrieve the following information: Validation URL - Apple provides the validation URL that you send to us when you create an Apple Pay session. Encrypted payment details - Apple encrypts the cardholder's payment details and returns them to your integration. After you receive the encrypted payment details, convert them to hexadecimal. Step 2. Integrate with the Payroc API Use our API to start the merchant session with Apple Pay and retrieve the startSessionResponse object. After you use the Apple Pay JS API to encrypt the cardholder's payment details, use our API to run the sale. Step 2a. Start an Apple Pay session To start an Apple Pay session with Apple, send a request to", "refs": { "workflowIds": [], "operationIds": [ "applePaySessions", "payment" ] } }, { "route": "/guides/payments/apple-pay/extend-your-integration", "type": "guide", "title": "Extend your integration", "description": "Extend your Apple Pay integration to add convenience fees or split payments between multiple merchants using the multi-merchant of record function.", "headings": [], "plainText": "After you set up Apple Pay to run a sale, you can extend your integration to include the following: Split a payment between merchants - Divide a payment with other merchants or third parties. Add a convenience fee - Apply a convenience fee to Apple Pay payments.", "refs": { "workflowIds": [], "operationIds": [] } }, { "route": "/guides/payments/apple-pay/set-up-apple-pay-merchant", "type": "guide", "title": "Set up Apple Pay for a merchant", "description": "Configure Apple Pay for a merchant by adding the domain verification file and registering the domain in the Self-Care Portal to generate a unique merchant domain ID.", "headings": [ "Before you begin", "Step 1. Add the domain verification file to the merchant's domain", "Step 2. Add the merchant's domain to the Self-Care Portal" ], "plainText": "Prerequisites: Authentication · Add Apple Pay to your integration After you integrate with the Apple Pay JS API and the Payroc API, you need to set up Apple Pay for each individual merchant. We then generate a unique ID for the merchant's domain that you need to start an Apple Pay session. To set up Apple Pay for a merchant, complete the following steps: Step 1. Add the domain verification file to the merchant's domain. Step 2. Add the merchant's domain to the Self-Care Portal. Before you begin Add the following subfolder to the merchant's domain: /.well-known Step 1. Add the domain verification file to the merchant's domain Log into the Self-Care Portal. From the side menu, select Settings, and then select Apple Pay Domains. Select DOWNLOAD DOMAIN VERIFICATION FILE. Add the file to the merchant's domain in the following subfolder: /.well-known/apple-developer-merchantid-domain-association Important: Do not change the name of the domain verification file. The file name must be apple-developer-merchantid-domain-association. Step 2. Add the merchant's domain to the Self-Care Portal Select ADD NEW DOMAIN. In the Domain field, enter the merchant's domain name, for example, website.com. Select Save. The Self-Care Portal redirects you to the Apple Pay Domains page where it displays the unique ID of the merchant's domain. Important: Store the unique ID of the merchant's domain. You need to send the unique ID when you start an Apple Pay Session. The Self-Care Portal also displays the Merchant Identifier, which you need if you want to add a convenience fee or split a payment with multiple merchants.", "refs": { "workflowIds": [ "accept-apple-pay" ], "operationIds": [] } }, { "route": "/guides/payments/apple-pay/split-a-payment-with-multiple-merchants", "type": "guide", "title": "Split a payment with multiple merchants", "description": "Split an Apple Pay payment between multiple merchants using the multi-merchant of record (MMoR) function by sending the multiTokenContexts array to Apple Pay and individual payment requests to our gateway.", "headings": [ "How it works", "Before you begin", "Integration steps", "Step 1. Update your Apple Pay integration", "Request parameters", "multiTokenContexts example", "Step 2. Send a payment request for each merchant" ], "plainText": "Prerequisites: Add Apple Pay to your integration · Set up Apple Pay for a merchant If you need to split an Apple Pay payment between multiple merchants or third parties, you can use the multi-merchant of record (MMoR) function within Apple Pay. With MMoR, the cardholder authorizes the total amount once, and then you send the separate amounts to each merchant or third party. How it works You send a request to the Apple Pay JS API that contains the amount for each merchant. Apple returns a cryptogram after your customer authorizes the total amount. You send a payment request to our gateway for each merchant. Each payment request contains the same cryptogram and the amount that the merchant should receive. Before you begin Integrate with Apple Pay. Set up Apple Pay for each merchant and store their merchant identifier. You must use Apple Pay JS API version 14 or later. Integration steps Update your Apple Pay integration. Send a payment request for each merchant. Step 1. Update your Apple Pay integration Update your Apple Pay integration to include the multiTokenContexts array in the ApplePayPaymentRequest. Each entry in the array represents a payment amount to each merchant. If your request is successful and the customer authorizes the payment, Apple Pay returns a cryptogram that you need to include in each payment request to our gateway. Request parameters Parameter Description merchantIdentifier Merchant identifier that we assigned when you set up the merchant with Apple Pay. externalIdentifier Order ID for the payment. This value must match the value for orderId in the payment request. merchantName Name of the merchant that you set up with Apple Pay. amount Amount that each merchant receives from the total amount. multiTokenContexts example \"multiTokenContexts\": [ { \"merchantIdentifier\": \"PMID-101\", \"externalIdentifier\": \"ORDER-A1\", \"merchantName\": \"Merchant 1\", \"amount\": \"100.00\" }, { \"merchantIdentifier\": \"PMID-102\", \"externalIdentifier\": \"ORDER-B7\", \"merchantName", "refs": { "workflowIds": [ "accept-apple-pay" ], "operationIds": [ "payment" ] } }, { "route": "/guides/payments/close-ach", "type": "guide", "title": "Close an ACH payment", "description": "Close an ACH payment: If NACHA returned an ACH payment and the merchant accepted an alternative payment method, you can use our API to close the return without re-presenting the payment to NACHA.", "headings": [ "How it works", "Your integration journey", "Things to consider", "Errors", "Step 1. View the payment details", "Request parameters", "Schema (request.path)", "Example request", "Request", "Response fields", "Schema (response.body)", "Example response", "Response (200)", "Step 2. Close the return", "Request parameters", "Schema (request.path)", "Example request", "Request", "Response fields", "Schema (response.body)", "Example response", "Response (200)" ], "plainText": "If NACHA returned an ACH payment and the merchant accepted an alternative payment method, you can use our API to close the return without re-presenting the payment to NACHA. Note: Use this method to permanently close a return. If you want to retry the payment, use our Re-present Payment method instead. How it works We email the merchant to let them know that NACHA returned an ACH payment. Merchant uses an alternative payment method to collect payment from their customer. Merchant uses their POS to close the return. Your integration journey View the payment details. Close the return. Things to consider When you close a return, don't use the paymentId that you use to retrieve the payment. In the response of the Retrieve Payment method, our gateway includes a returns array with a new paymentId, which you need to send in the Close Return request. ... \"returns\": [ { \"paymentId\": \"GIJXAU3WUJ\", \"date\": \"2025-06-23\", \"returnCode\": \"R01\", \"returnReason\": \"Insufficient Funds\", \"represented\": false, \"closed\": false, \"link\": { \"rel\": \"self\", \"method\": \"GET\", \"href\": \"https://api.payroc.com/v1/bank-transfer-payments/GIJXAU3WUJ\" } } ], ... Errors If your request is unsuccessful, we return an error. For more information about errors, see Errors. Step 1. View the payment details To view the details of the return, send a GET request to our Bank Transfer Payments endpoint. Endpoint Prefix URL Test api.uat. https://api.uat.payroc.com/v1/bank-transfer-payments/:paymentId Production api. https://api.payroc.com/v1/bank-transfer-payments/:paymentId Request parameters Schema (request.path) Path parameters for GET /bank-transfer-payments/{paymentId} Example request Request GET https://api.payroc.com/v1/bank-transfer-payments/{paymentId} Store Token Bank Transfer Payment curl https://api.payroc.com/v1/bank-transfer-payments/M2MJOG6O2Y \\ -H \"Authorization: Bearer \" Store Token Bank Transfer Payment import requests url = \"https://api.payroc.com/v1/bank-transfer-payments/M2MJOG6O2Y\" head", "refs": { "workflowIds": [], "operationIds": [ "closeBankTransferPayment", "getBankTransferPayment", "representBankTransferPayment" ] } }, { "route": "/guides/payments/google-pay", "type": "guide", "title": "Google Pay", "description": "Add Google Pay to your integration so merchants can accept Google Pay as a payment method for online transactions.", "headings": [ "How it works", "Guides", "Add Google Pay to your integration" ], "plainText": "Prerequisites: Authentication An AI skill is available for this guide, get it on the Skills Marketplace (GitHub). Google Pay® is a digital wallet application that Google customers can use to store payment card details and to pay for goods and services. When you add Google Pay to your integration, your merchants can accept Google Pay as a payment method for online transactions. When a customer uses Google Pay to make a payment, your integration communicates with Google Pay and the Payroc gateway to make the sale. How it works The following diagram shows the flow of a transaction with Google Pay. sequenceDiagram participant GP as Google Pay API participant YI as Your integration participant GW as Gateway rect rgba(0, 81, 194, 0.4) Note over GP,GW: Run a sale Note over YI: 1. Cardholder chooses to pay with Google Pay YI->>GP: 2. Request the cardholder's payment details GP-->>YI: 3. Return the encrypted payment details Note over YI: 4. Convert the payment details to hexadecimal format YI->>GW: 5. Send the payment details in a payment request GW-->>YI: 6. Return payment response end Cardholder chooses to pay with Google Pay, for example, they select the Google Pay button on the merchant's web page. Your integration requests the cardholder's payment details from Google Pay. Google Pay returns the cardholder's encrypted payment details. Your integration converts the cardholder's payment details to hexadecimal format. Your integration sends a request to our Payments endpoint with the cardholder's encrypted payment details in hexadecimal format. Our gateway returns a successful payment response to your integration. Guides Add Google Pay to your integration Run transactions with Google Pay.", "refs": { "workflowIds": [], "operationIds": [] } }, { "route": "/guides/payments/google-pay/google-pay-integrate", "type": "guide", "title": "Add Google Pay to your integration", "description": "Integrate Google Pay by retrieving encrypted payment details from the Google Pay API and submitting them to the POST /v1/payments endpoint with a digitalWallet paymentMethod type.", "headings": [ "Integration steps", "Before you begin", "Headers", "Errors", "Step 1. Integrate with the Google Pay API", "Step 2. Run a sale", "Example request", "Step 3. Register your integration" ], "plainText": "Prerequisites: Authentication When a customer uses Google Pay® to pay for goods or services on a merchant’s website or mobile app, use the Google Pay API to retrieve the customer’s encrypted payment details. You can then use our API to run a transaction with the encrypted payment details. Integration steps Integrate with the Google Pay API to retrieve encrypted payment details. Integrate with our API to run transactions. Register your integration. Before you begin Authenticate your requests before making API calls. If your request fails, see Errors. Headers To create the header of each GET request, you must include the following parameters: Content-Type: Include application/json as the value for this parameter. Authorization: Include your Bearer token in this parameter. curl -H \"Content-Type: application/json\" -H \"Authorization: \" To create the header of each POST request, you must include the following parameters: Content-Type: Include application/json as the value for this parameter. Authorization: Include your Bearer token in this parameter. Idempotency-Key: Include a UUID v4 to make the request idempotent. curl -H \"Content-Type: application/json\" -H \"Authorization: \" -H \"Idempotency-Key: \" Errors If your request is unsuccessful, we return an error. For more information about errors, see Errors. Step 1. Integrate with the Google Pay API To integrate with the web version of the Google Pay API, go to https://developers.google.com/pay/api/web/overview. During your integration with the Google Pay API, you need the following: merchantId - Merchant ID that Google assigned to you. gatewayMerchantId - Gateway ID, which is usually your processing terminal ID without the last three characters. For example, if your processingTerminalId is 9876001, your gatewayMerchantId is 9876. gateway – Name of the gateway that processes the transaction. Use the case-sensitive value of worldnet. Note: Payroc now owns the Worldnet gateway and uses it to", "refs": { "workflowIds": [], "operationIds": [] } }, { "route": "/guides/payments/hosted-fields", "type": "guide", "title": "Hosted Fields", "description": "Add secure, gateway-hosted payment fields to your own checkout page design using Hosted Fields.", "headings": [ "How it works", "Your integration journey", "Extend your integration" ], "plainText": "An AI skill is available for this guide, get it on the Skills Marketplace (GitHub). Use our Hosted Fields solution to add payment fields to your checkout page. You control the look and feel of the checkout page, but we host the fields to make them more secure. By integrating with Hosted Fields, you allow the merchant to: Accept payments from cards and bank accounts. Keep the design of their checkout page. Reduce their PCI-DSS compliance requirements. How it works Use our Hosted Fields solution to create a form that the customer uses to enter their payment details. After the customer submits their payment details, we generate a single-use token that represents the details. sequenceDiagram participant M as Merchant participant GW as Gateway rect rgba(0, 81, 194, 0.4) Note over M: 1. Checkout page loads the form with Hosted Fields Note over M: 2. Customer enters and submits their payment details M->>GW: 3. Hosted Fields sends the payment details to the gateway Note over GW: 4. Gateway creates a single-use token GW-->>M: 5. Gateway returns the single-use token Note over M: 6. Use the single-use token in follow-on actions end Your integration journey Authenticate your session - Create a session token to authenticate your integration each time you load Hosted Fields on a webpage. Create a payment form - Use our HTML and our Hosted Fields JavaScript Library to create a payment form. Run a sale - Use the single-use token to run a sale. Extend your integration After you integrate with Hosted Fields to run a sale, you can extend your integration with additional features, for example: Customize your payment form. Close a session. Save a customer's payment details. For more information about how to add these features to your integration, go to Extend your integration.", "refs": { "workflowIds": [], "operationIds": [] } }, { "route": "/guides/payments/hosted-fields/add-your-own-fields", "type": "guide", "title": "Add your own fields", "description": "Add your own HTML fields to Hosted Fields to capture extra customer or transaction information, such as address details for address verification.", "headings": [ "Step 1. Add your own HTML fields", "Step 2. Validate the data in the fields", "Step 2a. Add the onPreSubmit function", "Step 2b. Define the onPreSubmit function", "displayMissingFieldsError function", "Step 3. Handle the response", "Step 4. Retrieve the data from the fields", "Step 5. Create payment request" ], "plainText": "You can add your own HTML fields to capture additional information about the customer or the transaction, for example, address information for the address verification service (AVS). After you capture the customer’s address information, you can send it in the payment request. Important: If you add your own HTML fields, you are responsible for handling the additional information that you capture. To help you understand how to add your own fields, we have created a worked example that you can follow. In our example, we capture billing details from the customer and then use the billing details in the payment request. In our example, we complete the following actions: Add our own HTML fields. Validate the data in the fields. Handle the response. Retrieve the data from the fields. Create a payment request. Step 1. Add your own HTML fields In the following code block, we created a
to capture the customer's billing details and an error message for each required field.
*Required
*Required
*Required
ACH
\" \\ -H \"Content-Type: application/json\" \\ -d '{ \"channel\"", "refs": { "workflowIds": [], "operationIds": [ "bankTransferPayment", "payment" ] } }, { "route": "/guides/payments/hosted-fields/run-a-sale-tokenize", "type": "guide", "title": "Save payment details when running a sale", "description": "Save card or bank account payment details when running a sale by sending a POST request to the Payments or Bank Transfer Payments endpoint with a credentialOnFile object.", "headings": [ "Save payment details when running a sale", "Before you begin", "Integration steps", "Save card details when you run a sale", "Request parameters", "Schema (request.body)", "Example request", "Request", "Response fields", "Schema (response.body)", "Example response", "Response (201)", "Save bank account details when you run a sale", "Request parameters", "Schema (request.body)", "Example request", "Request", "Response fields", "Schema (response.body)", "Example response", "Response (201)", "Using the secure token" ], "plainText": "Prerequisites: Authentication · Run a sale Save payment details when running a sale You can use the single-use token from your existing Hosted Fields integration to save a customer's payment details at the same time that you run a sale. If you save a customer's payment details during a sale, our gateway uses the single-use token from Hosted Fields to charge the customer, and then saves the customer's payment details as a secure token. You can use the secure token multiple times, and it doesn't expire. To tokenize payment details during a sale, you need to send some additional parameters in your request to our API. You don't need to change the JavaScript configuration or authentication for your existing Hosted Fields integration. Before you begin Make sure that you've set up your Hosted Fields integration to run a sale with the single-use token from the submissionSuccess event. For more information, go to Run a sale. Authenticate your requests before making API calls. If your request fails, see Errors. Integration steps The steps that you need to follow depend on whether your single-use token represents card details or bank account details: If the single-use token represents card details, go to Save card details when you run a sale. If the single-use token represents bank account details, go to Save bank account details when you run a sale. Save card details when you run a sale To run a sale and tokenize the card details, you need to update your POST request to our Payments endpoint. Environment URL Test https://api.uat.payroc.com/v1/payments Production https://api.payroc.com/v1/payments Request parameters Important: The request includes parameters for functions and features that we don't cover in this guide. These functions and features might require additional integration effort and cost. For more information, contact our Integrations Team at integrationsupport@payroc.com. To save a customer's card details when you run a sale, update your request to our Payments en", "refs": { "workflowIds": [], "operationIds": [ "bankTransferPayment", "payment" ] } }, { "route": "/guides/payments/hosted-fields/save-payment-details", "type": "guide", "title": "Save a customer's payment details", "description": "Convert a Hosted Fields single-use token into a reusable secure token by sending a POST request to the Secure Tokens endpoint, enabling future card and bank account payments without recapturing payment details.", "headings": [ "Before you begin", "Integration steps", "Step 1. Update the JavaScript configuration", "Step 2. Convert the single-use token into a secure token", "Request parameters", "Schema (request.body)", "Example request", "Request", "Response fields", "Schema (response.body)", "Response example", "Response (201)", "Using the secure token" ], "plainText": "An AI skill is available for this guide, get it on the Skills Marketplace (GitHub). You can update your Hosted Fields integration to save a customer's payment details as a secure token without charging the customer. To tokenize the customer's payment details, you need to update the Hosted Fields JavaScript configuration, and then send a request to our Secure Tokens endpoint. You don't need to change your authentication process for your existing Hosted Fields integration. Before you begin Make sure that you've set up your Hosted Fields integration to handle the single-use token from the submissionSuccess event. For more information, go to Run a sale. Authenticate your requests before making API calls. If your request fails, see Errors. Integration steps Update the JavaScript configuration. Convert the single-use token into a secure token. Step 1. Update the JavaScript configuration In the JavaScript configuration, change the value for the mode parameter from payment to tokenization. Card ACH