Release Notes

The Terminal API is now available in the Run Developer! Connect your software to P2PE-validated, card-present acceptance solutions via Run Developer. Your customers can swipe, dip, or tap on an integrated card reader, and your POS will receive a tokenized card or a completed charge without card data ever touching your systems. Read more in our Terminal API Overview.

The following guides have been added to the Run Developer site under Guides > Payments > Card Present:

• Overview: Choosing between the unified and two-step integration paths, supported devices, and the end-to-end flow
• Getting Started: Environment, authentication, and terminal capabilities
• Interactions & Status: Polling, WebSockets, cancelling, and sessions
• Unified Charge Workflow: Running charge-card and handling declines and stage_errors
• Signatures & Receipts: Capturing signatures and printing or emailing receipts
• Surcharging on Device: Card-present surcharging for enrolled merchants
• Endpoints & Errors: Endpoint summary, response codes, and error messages

We have reorganized the API Reference into two sections based on authentication method. Please note the updated locations below.

• Processing (Payments and Terminal APIs): Authenticate with your Payments API key as a bearer token. Refresh API Keys has moved to its own Authentication section here.
• Reporting & Boarding (Reporting and Boarding APIs): Authenticate with OAuth 2.0 client credentials generated from Run Merchant or provided by your Run Integration Delivery rep.

New guide covering Visa’s Commercial Enhanced Data Program (CEDP) — Run’s implementation of Level 2/Level 3 data for commercial card interchange optimization:

• P3 Qualification guide: Documents all required fields to qualify a charge request for P3, including order-level fields, shipping fields, and the line_items[] array
• Supported on Cardpointe, Payroc, and Cybersource gateways
• Includes a complete example request and parameter reference tables
• Implementation notes covering comm_card detection, order_date format, tax reconciliation, and surcharge line-item handling

New guide section documenting the HPP edit endpoint:

• Hosted Payment Pages guide: Documents PUT /api/v1/hpp/{hpp_client_id} — update an existing payment page’s name, amount, amount range (min_amount/max_amount), lock settings, and form field configuration
• Existing fields are preserved unless explicitly overridden

New Test Cards guide consolidating all UAT test card and decline scenario references:

• Basic test cards for Visa, Mastercard, AMEX, and Discover
• UAT response code tables for all four card brands — charge a specific cent amount to trigger a targeted decline scenario (Cardpointe gateway only)
• Setup and Validate & Deploy pages now link to this guide for quick access

Updated the Runner.js Versions page with the full release history sourced from the production branch:

• Current stable release 1.5.5 clearly identified with a callout
• Complete version table from 1.4.0 through 1.5.5 with release dates and descriptions

Added a full iStream ACH implementation example to the Runner.js guide:

• Demonstrates last4 capture via the message event
• Shows accountTypeField and customerNameField wiring using native HTML elements
• Uses the onTokenize callback pattern

Runner.js - CYBS Gateway Example

Added a complete CYBS gateway integration example to the Runner.js guide:

• Uses cardNumberFieldSelector and cvvFieldSelector to target custom card/CVV iframe containers
• Expiration date handled via native <select> elements rather than Runner.js-rendered fields
• Includes full HTML form and JavaScript tokenization flow

New feature added for automated recurring payment processing:

• Billing Plans Guide: Configure payment frequency and let the system automatically process scheduled payments using tokenized vault data
• New API endpoints for creating and managing billing plans
• Includes security and compliance notes for PCI DSS and cardholder consent requirements

New endpoint added for vault payment account creation:

• POST /api/v1/vault_payment_accounts: Create vaulted payment accounts directly via API for secure storage of payment information
• Complements existing vault creation methods

Action Required: If you store customer payment information for recurring billing or future use, you must now include COF parameters in your charge requests.

• Card On File Guide
• New Required Parameters:cl
  • cof: Set to "C" (customer present) or "M" (merchant-initiated)
  • cof_sched: Set to "Y" (scheduled recurring) or "N" (one-time/unscheduled)
  • cof_perm: Optional, set to "Y" if customer gave explicit permission
• When to Use: Any transaction using saved payment methods, subscriptions, or recurring billing
• Non-compliance Risk: Transaction declines and potential penalties

New Feature: Real-time validation of bank account information during tokenization (iStream gateway).

• ACH Validation Guide
• What’s New: Runner.js tokenization responses now include risk_info object with validation results
• Decision Codes: A (Accept), W (Warning), D (Decline)
• Action: Check risk_info.decision before processing ACH transactions

New API Endpoint: Edit existing hosted payment pages without recreating them.

• PUT /api/v1/hpp/{hpp_client_id}: Update HPP properties dynamically
• Use Cases: Modify amounts, lock settings, customer information, or optional fields
• Note: Merchant ID (cc_mid) cannot be changed after creation

Documentation Enhancement: Added full copy-paste examples for each gateway.

• New Gateway Examples:
  • Cardpointe: Complete implementation with charge processing
  • Cybersource: Custom field selectors and styling
  • Payroc: Full validation and error handling
  • ACH (iStream/Fiserv): Bank account tokenization with validation
• What’s Included: HTML forms, initialization code, tokenization workflow, and backend integration

• order_id Parameter: Now auto-generated if not provided (previously required)
• Swagger Spec: Improved formatting and consistency across all endpoints

New comprehensive guide added covering:

• Vaults Guide: Creating vaults, adding payment methods, zero-dollar authorization, and best practices
• Enhanced charge endpoint with vault_holder_id parameter for vault management

• Release 1.4.3: Enhanced vault creation, gateway response integration, and Payroc gateway support
• Gateway Examples: Added implementation guides for Payroc Gateway and ACH (iStream and Fiserv ACH)
• Updated parameters table with improved descriptions and standardized terminology

Enhanced ACH payments guide with new required fields for Fiserv ACH compatibility:

• payment_description, ach_discretionary_data, entry_class, credit_or_debit
• Added minimum viable ACH transaction example

• Expanded Required Fields: Updated charge endpoint with 11 total required fields using “greatest common denominator” approach
• Transaction Status Mapping: Simplified ID mapping table to 9 core statuses
• Boarding Webhooks: Updated event_table_pk to merchant_id across all webhook examples
• Fixed documentation links and improved navigation structure