Skip to main content
Version: Lab (preview)

Changelog

Additions and updates to Pay Theory's API and SDKs

October 22, 2026​

Added to JS SDK​

  • transact accepts idempotencyKey. A retry with the same key returns the first response instead of charging twice. See Idempotency.
  • Each hosted field's state in stateObserver has iframeLoaded. It turns true once that field's iframe loads, so you can show fields before the SDK is ready.
  • tokenizePaymentMethod with expandedResponse: true returns FAILED with failure_code and failure_text when the processor rejects the payment method. Before, this was an ERROR string. Without expandedResponse, nothing changes.
  • The SDK publishes TypeScript declarations, paytheory-sdk.d.ts, on the same host as the SDK. See TypeScript.

Deprecated in JS SDK​

  • The confirmation flow: transact with confirmation: true, confirm, cancel, tokenizeObserver and captureObserver. To show the service fee before charging, read it from stateObserver and pass it as fee. See Deprecations.

Added to API​

  • createTransaction and createAuthorization accept idempotency_key. Retrying the same request with the same key returns the first response, including a decline, instead of creating a second payment. A changed request returns IDEMPOTENCY_KEY_PAYLOAD_MISMATCH.
  • The idempotencyLookup query returns a key's status (IN_PROGRESS or COMPLETED), the linked transaction or authorization, and when the record expires.
  • Merchants have max_transaction_amount, one limit in cents for card and ACH payments, including service fees. Pay Theory rejects a payment above it before processing, and marks a recurring payment above it MERCHANT_MAX_AMOUNT_EXCEEDED.

January 27, 2026​

Added to API​

  • Instructional Funding - New instructional funding API surface area

    • availableFundsBalance query with AvailableFundsBalance fields (hold/reserve balances, window status)
    • instruction query and Instruction object for daily settlement instructions
    • fundingTransfers query and FundingTransfer object for settlement batch transfers
    • createSettlementInstruction mutation to submit daily instruction amounts

  • Sandbox Mutations - New sandbox-only mutations for testing in sandbox environments

    • createSandboxAchReturn to generate ACH returns
    • createSandboxDispute and updateSandboxDisputeStatus to create and move disputes
    • prepareSandboxSettlementBatch and createSandboxSettlement to simulate settlements

Added to Webhooks​

  • New event types: AVAILABLE_FUNDS_BALANCE and FUNDING_TRANSFER
  • DELETED subtype documented (where supported) with payload examples

Added to Docs​

  • Instructional Funding guide with an example flow and related API links
  • Testing page updated with sandbox mutation links for lab environments

August 14, 2025​

Added to JS SDK​

  • PayTheory Messenger SDK - New module for digital wallet transaction processing
    • PayTheoryMessenger class for handling Apple Pay™, Google Pay™, and Paze transactions
    • initialize() function to establish secure messenger connection
    • getApplePaySession() function for Apple Pay merchant validation
    • processWalletTransaction() function for processing wallet payments with support for:
      • Apple Pay™ payment tokens
      • Google Pay™ payment tokens
      • Paze digital wallets
      • Transaction metadata and billing information
    • on() function for event listener registration supporting events:
      • ready - Messenger initialization complete
      • transaction_complete - Transaction success
      • transaction_error - Transaction failure
      • iframe_unloaded - Messenger iframe unloaded
    • destroy() function for cleanup and resource management
    • Static wallet type constants: PayTheoryMessenger.applePay, PayTheoryMessenger.googlePay, PayTheoryMessenger.paze

Added to API​

  • createWalletTransaction mutation added for processing digital wallet payments

    • Supports Apple Pay™, Google Pay™, and other wallet types via wallet_type parameter
    • Accepts encrypted digital_wallet_payload from wallet providers
    • Returns standard transaction response with wallet-specific details

  • createWalletAuthorization mutation added for wallet payment authorizations

    • Creates authorization holds for digital wallet transactions
    • Same parameters as createWalletTransaction but for auth-only flows
    • Returns authorization object for later capture

March 6, 2025​

Added to API​

  • Split Transactions - New comprehensive split functionality for distributing transaction funds
    • splits query added to retrieve split transactions with filtering and pagination
    • Split object schema introduced with fields for:
      • amount - Split amount in cents
      • account_code - Customer defined account code
      • reference - Customer defined reference
      • merchant - Associated merchant object
      • payment_method - Payment method used for transaction
      • settlement_batch - Settlement batch number when settled
      • metadata - Custom JSON metadata storage
    • SPLIT added as a new value to the MetadataAssociate enum for metadata management

February 12, 2025​

Added to API​

  • validatePaymentMethodOwnership query added to verify payment method ownership

    • Validates whether a provided card or bank account number matches a specific payment method
    • Returns boolean confirmation of ownership match
    • Requires PCI L1 compliance for usage

  • updateMerchantSettings mutation added for merchant configuration management

    • Allows updating merchant contact information (email, phone)
    • Supports social media links (Facebook, Instagram, LinkedIn, TikTok, Twitter)
    • Enables website URL configuration
    • Uses MerchantSettingsInput with all fields optional for partial updates

November 20, 2024​

Added to API​

  • createBatchCapture mutation added to API. Only works in sandbox environments. Captures all PENDING transactions for a merchant in a batch and shortly after creates a settlement for the merchant.
  • metadata added to Merchant schema
    • Can be passed in when calling createMerchant
    • Can be managed with the updateMetadata and deleteMetadata mutations
    • Can be requested in the merchant and merchants queries
    • Can be used to filter the merchants query
  • skip_validation added to the createPaymentMethod mutation. If set to true, the payment method will be created without validation.

Added to JS SDK​

  • skipValidation added to the tokenizePaymentMethod function. If set to true, the payment method will be created without validation.

October 4, 2024​

Added to API​

  • country_code was added to the Merchant and ListMerchant object
  • canadian_eft was added to the PaymentMethodInput for creating Canadian Bank accounts
  • issuing_country_code was added to the PaymentMethodToken schema
  • flag_for_review key added to Transaction schema

September 29, 2024​

Added to API​

  • country_code was added to the Merchant and ListMerchant object
  • canadian_eft was added to the PaymentMethodInput for creating Canadian Bank accounts
  • issuing_country_code was added to the PaymentMethodToken schema
  • flag_for_review key added to Transaction schema
  • merchant object of type ListMerchant was added to the Transaction schema
  • updateTransactionInReview mutation added to allow someone to approve or decline flagged transactions
  • one_time_use_token added to the createTransaction mutation to make it so that we immediately disable token after making the transaction
  • createReversal mutation added to API. Returns object with is_void and transaction_id in the response so you can tell if a payment was refunded, voided, or partially voided
  • barcode query added to API so you can fetch a single cash barcode from our system
  • createBarcode mutation added to API allowing cash barcodes to be created directly in the API without use of the SDK

Added to JS SDK​

  • country added to the payTheoryFields function to tell the SDK what fields to look for when initializing the Bank Fields. Defaults to USA but also accepts CAN
  • oneTimeUseToken added to the transact function parameters to make it so that we immediately disable token after making the transaction
  • New div IDs added for initializing the CAN bank fields:
    • bank-account-number - pay-theory-bank-account-number
    • bank-account-name - pay-theory-bank-account-name
    • bank-account-type - pay-theory-bank-account-type
    • bank-institution-number - pay-theory-bank-institution-number
    • bank-transit-number - pay-theory-bank-transit-number

Changed​

  • avs_status now included in the Authorization and Transaction schema
  • bank_account_type, bank_code, barcode_id, and card_type now included in the PaymentMethodToken schema
  • CardType enum with the following types added to schema: BUSINESS_CREDIT, BUSINESS_DEBIT, CREDIT_CARD, DEBIT_CARD, PREPAID_CARD
  • void_amount argument is deprecated in the createVoidForAuthorization mutation as only full voids are supported
  • createRefund mutation is deprecated. Recommend using createReversal call now
  • All successful transactions from the SDK/API will now have the state/status of PENDING instead of the potential of both PENDING or SUCCEEDED
    • PENDING transactions are now able to be voided to prevent funds from moving before settle