> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.runpayments.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runpayments.io/_mcp/server.

# Release Notes

## September 30, 2026

## Terminal API

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](/reference/terminal-api/overview).

To request a UAT device and credentials, please reach out to your Integration Delivery Lead or send a note to [integrations@runpayments.io](mailto:integrations@runpayments.io).

### Endpoints added

The following endpoints have been added to the Run Payments API Reference:

- ### Authentication: WebSocket
    - [`POST /api/ws-token`](/reference/terminal-api/authentication-web-socket/generate-ws-token): Generate a single-use WebSocket auth token.
- ### Terminals
    - [`GET /api/terminal`](/reference/terminal-api/terminals/list-terminals): List your terminals and their capabilities.
    - [`POST /api/terminal/{device_id}/connect`](/reference/terminal-api/terminals/connect-terminal): Connect a terminal session.
    - [`DELETE /api/terminal/{device_id}/disconnect`](/reference/terminal-api/terminals/disconnect-terminal): Disconnect a terminal session.
    - [`POST /api/terminal/{device_id}/ping`](/reference/terminal-api/terminals/ping-terminal): Ping a terminal.
- ### Card Read
    - [`POST /api/terminal/{device_id}/read-card`](/reference/terminal-api/card-read/read-card): Initiate a card read.
    - [`GET /api/terminal/{device_id}/read-card/{interaction_id}`](/reference/terminal-api/card-read/get-read-card-status): Get card read status.
    - [`DELETE /api/terminal/{device_id}/cancel/{interaction_id}`](/reference/terminal-api/card-read/cancel-read-card): Cancel a card read.
- ### Charge Card
    - [`POST /api/terminal/{device_id}/charge-card`](/reference/terminal-api/charge-card/initiate-charge): Read the card, optionally capture a signature, charge, and optionally deliver a receipt.
    - [`GET /api/terminal/{device_id}/charge-card/{interaction_id}`](/reference/terminal-api/charge-card/get-charge-card-status): Get charge status.
- ### Receipt
    - [`POST /api/terminal/{device_id}/print-receipt`](/reference/terminal-api/receipt/print-receipt): Print a receipt on the device.
    - [`POST /api/v1/send_receipt`](/reference/terminal-api/receipt/send-receipt): Email a receipt to your customer.

## Card Present Guides

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

- [Overview](/docs/guides/payments/card-present/overview): Choosing between the unified and two-step integration paths, supported devices, and the end-to-end flow
- [Getting Started](/docs/guides/payments/card-present/getting-started): Environment, authentication, and terminal capabilities
- [Interactions & Status](/docs/guides/payments/card-present/interactions-and-status): Polling, WebSockets, cancelling, and sessions
- [Unified Charge Workflow](/docs/guides/payments/card-present/unified-charge-workflow): Running `charge-card` and handling declines and `stage_errors`
- [Signatures & Receipts](/docs/guides/payments/card-present/signatures-and-receipts): Capturing signatures and printing or emailing receipts
- [Surcharging on Device](/docs/guides/payments/card-present/surcharging-on-device): Card-present surcharging for enrolled merchants
- [Endpoints & Errors](/docs/guides/payments/card-present/endpoints-and-errors): Endpoint summary, response codes, and error messages

## API Reference Navigation

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](/reference/authentication/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.

## June 9, 2026

## P3 Qualification (L2/L3)

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](/docs/guides/payments/p3-qualification): 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

## Hosted Payment Pages — Edit Endpoint

New guide section documenting the HPP edit endpoint:

- [Hosted Payment Pages guide](/docs/guides/payments/hosted-payment-pages): 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

## Test Cards

New [Test Cards guide](/docs/guides/payments/test-cards) 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

## Runner.js Versions

Updated the [Runner.js Versions](/docs/guides/tokenization/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

## Runner.js — iStream Example

Added a full iStream ACH implementation example to the [Runner.js guide](/docs/guides/tokenization/runner-js):

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

## March 2, 2026

## Cybersource Launch

### Runner.js - CYBS Gateway Example

Added a complete CYBS gateway integration example to the [Runner.js guide](/docs/guides/tokenization/runner-js):

- 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

### Charge API Updates

- **Cybersource required fields**: The following fields are now documented as required when processing through the Cybersource gateway: `name`, `address2`, `region`, `country`, `phone`, `email`.
- **Disclaimer added**: The Charge endpoint description now includes a note clarifying that documented requirements span all compatible gateways — not all fields apply to every integration.

## Additional Updates

### Gateway Response Codes

New reference guide added for understanding processor responses:

- [Gateway Response Codes](/docs/guides/payments/gateway-response-codes): Documents `respproc`, `respcode`, `respstat`, and `resptext` fields returned on charge responses
- Current coverage includes **Cardpointe (PPS)** response codes; additional gateway support coming soon

### Hosted Payment Pages - Amount Range Support

New optional fields added to the HPP create endpoint:

- **`min_amount`**: Minimum transaction amount. Only valid when `lock_amount` is `false`.
- **`max_amount`**: Maximum transaction amount. Only valid when `lock_amount` is `false`.

### Merchant Deleted Webhook

New boarding webhook event added:

- **`merchant.deleted`**: Triggered when a merchant record is deleted from a Partner. Includes merchant details such as `merchant_id`, `dba_name`, `deleted_by`, and timestamp. See the [Boarding Webhooks guide](/docs/guides/webhooks/boarding-webhooks) for the full payload reference.

## January 8, 2026

### Billing Plans

New feature added for automated recurring payment processing:
- [Billing Plans Guide](/docs/guides/payments/billing-plans): 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

### Vault Management Enhancements

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

## November 14, 2025

### Card On File (COF) - Required for Stored Credentials

**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](/docs/guides/payments/card-on-file)
- **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

### ACH Account Validation

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

- [ACH Validation Guide](/docs/guides/payments/ach-validation)
- **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

### Hosted Payment Pages - Edit Endpoint

**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

### Runner.js - Complete Integration Examples

**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

### API Updates

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

## September 25, 2025

### Vaults & Customer Management

New comprehensive guide added covering:
- [Vaults Guide](/docs/guides/payments/vaults): Creating vaults, adding payment methods, zero-dollar authorization, and best practices
- Enhanced charge endpoint with `vault_holder_id` parameter for vault management

### Runner.js Enhancements

- **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

### ACH Payment Updates

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

### API Requirements & Documentation

- **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

## September 17, 2025

### Webhooks Documentation

The following webhook guides have been added to the Run Developer site:
- [Webhooks Overview](/docs/guides/webhooks/overview): Introduction to webhook functionality and implementation.
- [Boarding Webhooks](/docs/guides/webhooks/boarding-webhooks): Setup and configuration of webhooks for boarding events.

### Boarding API Enhancements

The following endpoint has been added to the Boarding API reference:
- [`GET /boarding/v1/merchants`](/reference/reporting-boarding/boarding-api/list-merchants): Retrieve a list of merchants with optional filtering and pagination.
- Updated existing endpoints with more detailed request and response data

## August 11, 2025

### Hosted Payment Page API

Generate links on-the-go with our HPP API. Customize a payment page with transaction-specific parameters and share the link directly to your customer for payment.

- The Payments API reference has been updated to include the [`POST /hpp`](/reference/payments-api/create-hosted-payment-page) endpoint.

This is the first release of many for this API, and we will keep you updated as more functionality is added to this feature. An accompanying guide will be added to our docs site in the coming weeks. 

### Reporting API 

Transaction Status ID Mapping

- The Reporting API reference has been udpated to show trans_status_id in the response.
- A guide providing `trans_status_id` mapping has been added to our guides (See [ID Mapping](/docs/guides/payments/id-mapping)).

Custom Fields 

- Transaction and Account level custom fields have been added to the Charge endpoint API reference. 
- A guide on how to use Custom Fields in Run Developer and Run Merchant has been added. 

### Runner.js Updates

We have expanded the footprint of Runner.js documentation. Please note the updated URLs and updated locations of information below. 

[Tokenize](/docs/get-started/tokenize) page: 
- Versioning information has been added to the guide. The latest version of Runner.js at the time of this release is 1.4.2.
- Runner.js sample code for ACH has been added. Use the tabs at the top of the example in [step 2](/docs/get-started/tokenize#usage) of the Usage section to toggle between Card and ACH.

[Runner JS](/docs/guides/tokenization/runner-js) page has been created.
- This page will serve as the overview for Runner.js moving forward. 
- Runner.js parameters that previously were located in in the `Get Started` guide have been moved to this page. 
- Implementation examples of Runner.js for our supported gateways have been moved to this page. 

The [Runner.js Versions](/docs/guides/tokenization/versions) page has been created.
- Version tracking and descriptions have been added to this page.

## May 9, 2025

## Reporting & Boarding API Authentication

The following endpoint has been added to the API Reference: 

- [`POST /oauth/token`](/reference/reporting-boarding/authentication/get-access-token):
    Retrieve an access token for the Reporting or Boarding APIs. To toggle the URL between Boarding and Reporting API token requests, click the url on the API reference.

Minor cleanup of documentation reference links.

## April 25, 2025

## April Updates

### Boarding API

The Run Developer Boarding API is now available in the Run Developer center! For additional information regarding the Boarding API and to request credentials, please reach out to your Integration Delivery Lead or send a note to [integrations@runpayments.io](mailto:integrations@runpayments.io). 

### Guides added
The following guides have been added to the Run Developer site: 
- [Boarding API Overview](/docs/guides/boarding/boarding-api-overview): Start here to learn abou the basics of the Boarding API. 

### Endpoints added
The following endpoints have been added to the Run Payments API Reference: 

- ### Boarding API
    - [`POST /boarding/v1/merchants`](/reference/reporting-boarding/boarding-api/create-merchant): Create a merchant in Run Partner.
    - [`GET /boarding/v1/merchant:id`](/reference/reporting-boarding/boarding-api/get-merchant): Retrieve a single merchant's details.

## April 1, 2025

## Welcome to Run Developer!

### New Run Developer Launch

Welcome to Run Developer! This site provides integration guides and API reference docs for the most recent releases of all our products. As new features are launched, additional release notes will be shared here. 

### Guides added
The following guides have been added to the Run Developer site: 
- [Get Started](/docs/get-started/overview): Everything you need to run your first payment. 
- [ACH Payments](/docs/guides/payments/ach-payments): Process ACH payments using the Payments API.
- [Merchant Surcharge Program](/docs/guides/payments/merchant-surcharge-program): Implement a compliant surcharge program with the Payments API. 

### Endpoints added
The following endpoints have been added to the Run Payments API Reference: 
- ### Authentication
    - [`POST /api_keys/refresh`](/reference/authentication/refresh-api-keys): Refresh your API key for the Payments API.
    
- ### Payments
    - [`POST /charge`](/reference/payments-api/process-charge): Charge a payment account.
    - [`POST /capture`](/reference/payments-api/capture-transaction): Capture an authorized payment.
    - [`POST /void-or-refund`](/reference/payments-api/void-or-refund-transaction): Refund-or-void an authorization or transaction.
    - [`GET /surcharge`](/reference/payments-api/check-surcharge): Check if a transaction will incur a surcharge fee. 
- ### Reporting
    - [`GET /transactions`](/reference/reporting-boarding/reporting-api/get-transactions)
    - [`GET /deposits`](/reference/reporting-boarding/reporting-api/get-deposits)
    - [`GET /chargebacks`](/reference/reporting-boarding/reporting-api/get-chargebacks)
    - [`GET /adjustments`](/reference/reporting-boarding/reporting-api/get-adjustments)