Skip to content

payroc/transaction

v0.2.0MIT

Skills for payment transaction integration

check-ebt-balance

Guides developers through checking an EBT (Electronic Benefits Transfer) card balance via the Payroc API (POST /v1/cards/balance). Use this skill when the user wants to query an EBT card balance, implement an EBT balance inquiry, check SNAP balance or EBT Cash account funds, look up available benefits on a food stamp or EBT card, integrate EBT balance checking into a POS system, or work with the /v1/cards/balance endpoint. Also use when the user asks about foodStamp or EBT cash balances, benefit card balance lookup, or wants to check how much EBT credit is available on a card before a transaction — even if they don't use the phrase "balance check" or "EBT API" explicitly. Do NOT use for processing, charging, or refunding an EBT card; those operations require separate payment skills.

create-single-use-token

Guides developers through creating a Payroc single-use token for one-time payment use (POST /v1/processing-terminals/{processingTerminalId}/single-use-tokens). Use this skill when the user wants to: create a single-use token; tokenize card, ACH, or PAD details for immediate one-time use; capture payment details client-side without transmitting raw card data to the server; generate a short-lived (30-minute) token for a single payment; work with the /single-use-tokens endpoint; ask how to avoid handling raw card numbers server-side; pass payment details securely from client to server for a single transaction; or understand how single-use tokens differ from secure/reusable tokens. Do NOT use this skill when the user wants to save a payment method for future or recurring use, create a reusable/secure token, or set up recurring billing — those require the save-a-payment-method skill.

integrate-apple-pay

Guide an ISV developer or merchant through integrating Apple Pay with Payroc's payments API from merchant setup through a first successful test transaction. Use this skill whenever someone asks about adding Apple Pay to their Payroc integration, implementing Apple Pay on their checkout page, handling Apple Pay sessions with Payroc, processing digital wallet payments via Apple Pay, or getting Apple Pay working with the Payroc gateway — even if they don't explicitly mention "integration" or ask for step-by-step guidance.

integrate-google-pay

Guide an ISV developer or merchant through integrating Google Pay with Payroc's payments API from merchant setup through a first successful test transaction. Use this skill whenever someone asks about adding Google Pay to their Payroc integration, implementing Google Pay on their checkout page, processing digital wallet payments via Google Pay, or getting Google Pay working with the Payroc gateway — even if they don't explicitly mention "integration" or ask for step-by-step guidance.

integrate-hosted-fields

Guide an ISV developer or merchant through integrating Payroc's Hosted Fields from credential setup to first successful test transaction. Use this skill whenever someone asks about integrating Payroc Hosted Fields, embedding card input fields or a payment form in their own checkout page, using the Payroc JS payment library, generating a Payroc session token, tokenizing payment details with Payroc, or getting Payroc embedded payments working in their application — even if they don't explicitly mention "integration" or ask for step-by-step guidance. Also use it when a developer has HPP working and asks about the embedded alternative.

integrate-hosted-payment-pages

Guide an ISV developer or merchant through integrating Payroc's Hosted Payment Pages (HPP) from credential setup to first successful test transaction. Use this skill whenever someone asks about integrating Payroc Hosted Pages, implementing HPP, setting up a Payroc payment form, generating a Payroc auth hash, handling a Payroc receipt callback, getting Payroc payments working in their application, running a pre-authorization, capturing a pre-auth, holding funds on a card, authorize and capture flows, saving or tokenizing a customer's card on the Payroc Hosted Page, getting a Payroc secure token or CARDREFERENCE, or setting up recurring billing, subscriptions, repeat payments, payment plans, free trials, installments, or merchant-initiated transactions on Payroc — even if they don't explicitly mention "integration" or ask for step-by-step guidance.

integrate-payment-links

Guide a developer through integrating Payroc Payment Links — creating shareable payment URLs, distributing them by email, and managing their lifecycle (retrieve, list, update, deactivate, view sharing history). Use this skill whenever someone asks about Payroc payment links, generating a payment URL to send to a customer, sending a payment request by email, building an invoice payment flow, setting up a donation link, creating a hosted payment link, sharing or re-sharing a link, updating or expiring a payment link, or deactivating a link — even if they don't explicitly say "payment links". Also trigger when a developer has a Payroc API key and wants to charge customers without embedding a payment form in their site.

integrate-payroc-app-switching

Guides an Android developer whose POS app runs on the same payment terminal as the Payroc App through card-present payments with Payroc Cloud app switching: start the Payroc App service, submit the instruction over REST, switch the screen to the Payroc App for the card, poll, read the result from the payment, and switch back. Use it whenever someone mentions Payroc app switching, switching between their POS app and the Payroc App, launching the Payroc App from their own Android app, a POS that runs on the terminal itself, MITCActivity, PBCService, wn.pax.mitc, the overlay (draw over other apps) permission for Payroc payments, or putting a POS app on the Paxstore. Covers sales, unreferenced refunds and signatures on the same device, cancels and timeouts, and recovering a sale after lost connectivity. Do NOT use it for a POS on a separate computer, tablet or phone that sends sales to a terminal (integrate-payroc-cloud), for Tap to Pay on iPhone, or for online checkouts.

integrate-payroc-cloud

Guides developers through in-person, card-present sales and refunds with Payroc Cloud, the semi-integrated API where a POS sends instructions via the Payroc gateway to a payment device. Use whenever the user mentions Payroc Cloud, "pay by cloud", semi-integrated card-present payments, sending a sale/refund/signature to a terminal or card reader via the API, payment-, refund- or signature-instructions, polling an instruction, or cloud device payments. Covers the async submit, poll, follow-link, retrieve flow, idempotency, cancelling an in-progress instruction, referenced vs unreferenced refunds, reversals, signature capture, closed-loop reads, and finding a device serialNumber (GET /devices). Do NOT use for card-not-present flows, Hosted Fields, Hosted Payment Pages or Payment Links (separate skills), for setting up or pairing a device (out of scope; starts once a device serial number exists), or for a POS app on the same Android device as the Payroc App (integrate-payroc-app-switching).

look-up-card-details

Guide a developer through calling the Payroc BIN lookup API (POST /v1/cards/bin-lookup) to retrieve card metadata — card brand (Visa, Mastercard, Amex), country of issue, debit/credit indicator, healthcare/FSA/HSA flag, and surcharging eligibility — before or without processing a transaction. Use this skill when a developer asks about looking up card details via the Payroc API, identifying a card network or brand from a BIN or card number, checking whether a card is debit or credit, checking surcharge eligibility for a card, doing a BIN lookup, checking the card's issuing country, or checking if a card is FSA/HSA-linked. Also use when the developer has a card number (or its first 6–8 digits) and wants to know what kind of card it is — even if they don't use the term "BIN lookup". Do NOT use for card number format validation (Luhn check), processing a card payment, pre-authorization, refunds, configuring surcharging on a terminal, or general surcharging setup — those are separate skills.

manage-subscriptions

Guides developers through managing an existing Payroc repeat-payments subscription or payment plan after initial setup. Use this skill when the user wants to update or modify an existing subscription, cancel or deactivate a Payroc subscription, reactivate a cancelled subscription, manually trigger a payment on a subscription, change a subscription's amount or end date, pause or adjust collection cycles, list or retrieve subscriptions or payment plan details, or use the /v1/processing-terminals/{id}/payment-plans/{id} (PATCH/DELETE) or /v1/processing-terminals/{id}/subscriptions endpoints (including the deactivate, reactivate, and pay sub-endpoints) — even if they don't use the word "subscription" explicitly. Do NOT use for: creating a brand-new payment plan or enrolling a customer in a plan for the first time (use set-up-a-payment-plan instead), one-time card sales or refunds, saving or tokenizing a payment method, event webhook subscriptions, or payment links.

refund-a-card-payment

Guides developers through refunding a Payroc card (credit/debit) payment via the Payroc API. Use this skill when the user wants to refund a card payment or card transaction, issue a credit back to a cardholder's card, send money back to a credit or debit card, process a return for a card payment, work with the /v1/payments/{paymentId}/refund or /v1/refunds endpoints, create a referenced refund (using a paymentId) or an unreferenced refund (providing card details directly), issue a partial refund on a card payment, adjust or void a card refund, reverse or cancel a card refund (remove a refund from an open batch), look up or list card refund records, or build card refund functionality into a payment integration. Do NOT use for ACH or bank-transfer refunds (use refund-an-ach-payment instead), voiding or reversing a pre-authorization hold, or cancelling an unsettled card payment before capture.

refund-an-ach-payment

Guides developers through returning funds for an ACH (bank transfer) payment via the Payroc API. Use this skill to refund an ACH or bank transfer payment, return money to a customer's bank account, reverse or void a settled or open-batch bank transfer, issue a referenced refund (linked to a paymentId) or an unreferenced refund (standalone, no paymentId), process a PAD (Canadian pre-authorized debit) refund, or work with the /v1/bank-transfer-payments/{id}/refund or /v1/bank-transfer-refunds endpoint. Also for the difference between ACH reversals and refunds and choosing the right method, NACHA return codes on a refund, tracking ACH refund status, re-presenting a returned ACH payment to retry collection (/v1/bank-transfer-payments/{id}/represent), or closing a return after the customer paid another way (/v1/bank-transfer-payments/{id}/close). Does NOT cover card payment refunds (use refund-a-card-payment), taking new ACH payments, verifying bank accounts, or viewing ACH deposit reports.

run-a-card-sale

Guides developers through running a card sale (immediate-capture payment) via the Payroc Payments API (POST /v1/payments). Use this skill when the user wants to process a card payment, charge a credit or debit card, run a card sale or transaction, take or collect a card payment, implement a direct-API card payment (server-to-server), accept a card payment online or in-store, process a MOTO payment, or use a card token or single-use token to charge a customer. Also use when the user asks about card payment channels (pos/web/moto), card entry methods, what fields are required for a card payment request, how to get a paymentId from a sale, or how to submit a card payment and handle the response — even without the words "skill" or "payments API". Do NOT use for pre-authorization (autoCapture: false), refunds, reversals, ACH/bank-transfer payments, 3-D Secure authentication, or Hosted Fields / Hosted Payment Pages (embedded UI card input) — those are separate skills.

run-a-pre-authorization

Guides developers through running a card pre-authorization via the Payroc Payments API (POST /v1/payments with autoCapture: false), then capturing or reversing it. Use this skill when the user wants to hold funds on a card without immediately capturing, run a pre-auth, authorize a card payment for later capture, implement a hotel or car-rental hold pattern, build a deferred-capture payment flow, capture a pre-authorized payment, void or reverse a pre-authorization, or adjust a pre-authorization amount before capture — even if they don't use the word "pre-authorization" explicitly. Also trigger for questions about the difference between a sale and a pre-auth, or how to capture a held amount. Do NOT use for immediate card sales (autoCapture: true), ACH/bank-transfer payments, refunds on settled transactions, 3-D Secure authentication, or tokenization — those are separate skills.

run-a-sale-with-3ds

Guide a developer through implementing a 3-D Secure (3DS) card sale using the Payroc API — sending a card token through the Payroc MPI service for cardholder authentication, then posting the payment with the resulting mpiReference. Use this skill when someone asks about 3-D Secure payments, 3DS integration, 3DS2, SCA (Strong Customer Authentication), verifying cardholder identity for online card payments, running a card sale with 3DS, implementing Visa Secure, Mastercard Identity Check, or Verified by Visa. Also use when the developer wants to reduce fraud liability using 3-D Secure, add 3DS cardholder authentication to a web checkout, use the Payroc MPI service or mpi endpoint, or include a threeDSecure object or mpiReference in a payment request — even if they don't say "3DS" explicitly. Do NOT use for card sales without 3DS authentication, refunds, ACH payments, or card tokenization alone.

save-a-payment-method

Guides developers through saving and tokenizing customer payment details via the Payroc Secure Tokens API (POST /v1/processing-terminals/{processingTerminalId}/secure-tokens). Use this skill to: save a card or bank account (ACH/PAD) for future use without charging it now; tokenize card details into a reusable vault token (secureTokenId); implement card-on-file or bank-account-on-file storage; save payment details to enable future merchant-initiated charges (recurring, installment, or unscheduled); manage stored tokens (retrieve, list, delete, or update account details); or replace a customer's saved card with a new one. Do NOT use this skill to create a single-use token for a one-time transaction (use create-single-use-token), set up recurring billing schedules or payment plans (use set-up-a-payment-plan or manage-subscriptions), charge a customer using a saved token (use run-a-card-sale), or take a bank transfer/ACH payment right now (use take-an-ach-payment).

set-up-a-payment-plan

Guides developers through creating and configuring recurring / repeat payments with Payroc — building a payment plan template and enrolling customers by creating new subscriptions. Use this skill when the user wants to implement recurring billing, repeat payments, subscription billing, scheduled payments, installment plans, automatic recurring charges, or payment schedules with Payroc. Also use when the developer asks about creating payment plans, enrolling customers in subscriptions, the /v1/processing-terminals/{id}/payment-plans or /v1/processing-terminals/{id}/subscriptions endpoints, or how to charge a customer repeatedly on a defined schedule — even if they don't use the word "skill" or "repeat payments" explicitly. Do NOT use for: saving or tokenizing a payment method (use save-a-payment-method), managing or updating existing subscriptions (use manage-subscriptions), or one-time card or ACH payments.

take-an-ach-payment

Guide a developer through accepting ACH (Automated Clearing House) or PAD (Pre-Authorized Debit) bank transfer payments via the Payroc API (POST /v1/bank-transfer-payments). Use this skill to accept ACH payments, collect bank transfer payments, process direct debit or eCheck payments, charge a customer's bank account (checking or savings), implement bank account billing, set up recurring ACH charges, or tokenize bank account details for future charges. Also covers, as steps of the integration: reversing (voiding) a payment before settlement, re-presenting a returned ACH transaction (NSF / closed account retry), refunding within that flow, and single-use bank account tokens (singleUseToken type) from a Hosted Fields session. Does NOT cover: refunding, reversing, re-presenting or closing a returned ACH payment as the primary goal (use refund-an-ach-payment), viewing ACH deposit reports, verifying bank accounts, card payments, or single-use card tokens.

verify-bank-account

Guides developers through verifying a bank account via the Payroc API (POST /v1/bank-accounts/verify). Use this skill when the user wants to verify or pre-validate a bank account before a bank transfer, check whether a specific bank account is valid for ACH or PAD, validate ACH routing numbers or PAD transit/institution numbers, call or integrate the /v1/bank-accounts/verify endpoint, implement bank account verification in a payment integration, or debug errors returned by the bank account verify endpoint. Also use when the user asks what verified: false means, how idempotency applies to the verify call, or how to handle verification outcomes in application logic — even if they don't use the word "verify" explicitly. Do NOT use for general ACH or bank transfer payment processing that does not involve the verify endpoint.