Skip to main content
emisar

Braintree billing operations

v0.2.0

Investigate Braintree payment failures, duplicate charges, refunds, recurring billing and disputes, and perform reviewed billing corrections.

22 allowed by default 13 need approval by default
Pack ID
braintree
Vendor
emisar
OS
linux
Actions
35
Required binaries. Install these on the host before relying on the pack — an action that calls a missing one fails at run time.
python3

Install

emisar pack install fetches this pack, re-validates it, and verifies its content hash against the --hash below — the exact bytes this page was rendered against, so a tampered copy is rejected — before copying it into the runner's packs dir. The command reloads a running daemon itself; no manual restart.

on the runner host 
sudo emisar pack install braintree --hash sha256:dc9f6807dc55ad3ab14c1eddcf036ba36391b9653376ddad6e2639384a1766cf

Setup

Uses Python 3.10 or newer with its standard library and system CA certificates. Store credentials in the runner's private environment file and allowlist the variables below in execution.inherit_env . Every action uses a fixed API operation; credentials and evidence stay out of process arguments.

Environment

Set these on the runner host, then add each name to execution.inherit_env so the value reaches the action.

  • BRAINTREE_PUBLIC_KEY required

    Create API credentials in the Braintree Control Panel under API Keys. Use a dedicated user with the billing, transaction and dispute permissions required by enabled actions; sandbox and production credentials are separate.

  • BRAINTREE_PRIVATE_KEY required

    Private key paired with BRAINTREE_PUBLIC_KEY from the same Braintree API credentials entry. Store it only on the runner.

  • BRAINTREE_ENVIRONMENT default sandbox

    Use sandbox or production. Every correction must explicitly confirm the configured environment.

  • BRAINTREE_EVIDENCE_DIR

    Optional absolute directory containing reviewed evidence files readable by the runner. Required only for evidence_file_info and upload_dispute_file; regular PDF, PNG or JPEG files only.

Notes

  • Use account and merchant_accounts to identify the processing account and currency. Resolve legacy Control Panel or SDK IDs with resolve_id, then retrieve the returned GraphQL ID before acting.
  • Amounts are decimal strings in major currency units, supporting whole amounts and two or three decimal places. Preserve currency and merchant-account context throughout an investigation.
  • Search customer, transaction, refund, subscription and dispute records, then follow returned links. Customer payment methods and transactions have their own paginated actions; transaction/refund history and subscription transaction IDs have explicit local offsets.
  • Refund, capture and void use Braintree apiRequestKey deduplication for 30 days after the initial request completes. Preserve operation_id and identical parameters. Other corrections have no provider request deduplication; never repeat an ambiguous charge or evidence action before reconciliation.
  • retry_subscription only collects the entire reviewed positive past-due balance. Braintree clears the whole balance on success, even when a reduced manual retry is used elsewhere. This pack refuses that implicit debt waiver. Subscription changes check updatedAt; this is not an atomic compare-and-write.
  • Stage text or a reviewed file, inspect the dispute and evidence, then separately finalize with submit_dispute_evidence. File upload accepts one PDF/JPEG/PNG up to 4 MB and checks the SHA256 returned by evidence_file_info. Finalization verifies the evidence inventory; coordinate other writers because Braintree has no atomic compare-and-submit.
  • GraphQL supports the documented evidence categories. PayPal disputes needing EVIDENCE_TYPE, TRACKING_URL or sequence-number grouping must be completed in the Braintree Control Panel; those fields are absent from the public GraphQL input schema.
  • Calls use fixed Braintree HTTPS endpoints and Braintree-Version 2026-09-08. GraphQL errors fail the action even when HTTP status is 200. Results exclude arbitrary custom fields, raw payment credentials and signed evidence URLs.
  • Local schema-validated fixtures verify request contracts and failure handling. Live provider compatibility requires a governed read against the operator's configured Braintree merchant.

Verify it works

Runs braintree.account, a low-risk read that confirms the pack can reach its target. Run it on the host once the pack is installed; pack install runs it for you.

on the runner host 
sudo emisar pack verify braintree

Install and configure a pack walks through the whole sequence on a host.

Actions 35 total

View on GitHub
  • braintree.accept_dispute script high High — service-affecting

    Accept a dispute

    Accept the dispute and forfeit the disputed funds. This final decision cannot be undone.

    View source on GitHub
  • braintree.account script low Low — read-only or trivially reversible

    Show merchant identity

    Show the authenticated Braintree merchant identity, status, and timezone.

    View source on GitHub
  • braintree.cancel_subscription script high High — service-affecting

    Cancel a subscription

    Cancel one subscription irreversibly; existing transactions and refunds remain in history.

    View source on GitHub
  • braintree.capture_transaction script high High — service-affecting

    Capture an authorization

    Submit one authorized transaction for settlement with an explicit amount.

    View source on GitHub
  • braintree.customer script medium Medium — changes state, easily reversible

    Show customer

    Show one Braintree customer with diagnostic state and billing linkage. Uses selected fields; excludes raw custom fields and payment credentials. Nested arrays return at most ten entries with explicit overflow flags.

    View source on GitHub
  • braintree.customer_payment_methods script low Low — read-only or trivially reversible

    List customer payment methods

    List one page of customer payment methods with continuation for billing investigation.

    View source on GitHub
  • braintree.customer_transactions script low Low — read-only or trivially reversible

    List customer transactions

    List one page of customer transactions with continuation for billing investigation.

    View source on GitHub
  • braintree.customers script medium Medium — changes state, easily reversible

    Search customers

    List one bounded page of Braintree customers matching the supplied criteria. Blank optional criteria intentionally impose no filter; returned cursors continue the same search.

    View source on GitHub
  • braintree.dispute script low Low — read-only or trivially reversible

    Show dispute

    Show one Braintree dispute with diagnostic state and billing linkage. Includes evidence inventory, deadlines, status history and the evidence hash used for final submission. Nested arrays return at most ten entries with explicit overflow flags.

    View source on GitHub
  • braintree.dispute_evidence script low Low — read-only or trivially reversible

    List evidence inventory for one dispute

    List one local page of evidence inventory for one dispute. The provider returns an array; offset continues it without silently dropping entries.

    View source on GitHub
  • braintree.dispute_evidence_text script high High — service-affecting

    Show one dispute text evidence item

    Show one stored text evidence item for review. Returns at most 20000 characters and an explicit truncation flag; this may expose sensitive customer evidence.

    View source on GitHub
  • braintree.disputes script low Low — read-only or trivially reversible

    Search disputes

    List one bounded page of Braintree disputes matching the supplied criteria. Blank optional criteria intentionally impose no filter; returned cursors continue the same search.

    View source on GitHub
  • braintree.evidence_file_info script low Low — read-only or trivially reversible

    Inspect an evidence file

    Show the size, type, and SHA256 of one staged PDF, PNG, or JPEG without exposing file contents.

    View source on GitHub
  • braintree.merchant_accounts script low Low — read-only or trivially reversible

    List merchant accounts

    List the merchant's processing accounts with currency, status, and default designation.

    View source on GitHub
  • braintree.payment_method script low Low — read-only or trivially reversible

    Show payment method

    Show one Braintree payment method with diagnostic state and billing linkage. Uses selected fields; excludes raw custom fields and payment credentials. Nested arrays return at most ten entries with explicit overflow flags.

    View source on GitHub
  • braintree.plan script low Low — read-only or trivially reversible

    Show subscription plan

    Show one Braintree subscription plan with diagnostic state and billing linkage. Uses selected fields; excludes raw custom fields and payment credentials. Nested arrays return at most ten entries with explicit overflow flags.

    View source on GitHub
  • braintree.refund script low Low — read-only or trivially reversible

    Show refund

    Show one Braintree refund with diagnostic state and billing linkage. Uses selected fields; excludes raw custom fields and payment credentials. Nested arrays return at most ten entries with explicit overflow flags.

    View source on GitHub
  • braintree.refund_transaction script high High — service-affecting

    Issue a refund

    Refund an explicit amount from one settling or settled transaction. Multiple partial refunds are supported; refunding does not cancel a subscription.

    View source on GitHub
  • braintree.refunds script low Low — read-only or trivially reversible

    Search refunds

    List one bounded page of Braintree refunds matching the supplied criteria. Blank optional criteria intentionally impose no filter; returned cursors continue the same search.

    View source on GitHub
  • braintree.remove_dispute_evidence script high High — service-affecting

    Remove staged dispute evidence

    Remove one evidence item and read the dispute back to verify its absence.

    View source on GitHub
  • braintree.resolve_id script low Low — read-only or trivially reversible

    Resolve a legacy identifier

    Resolve one control-panel or SDK identifier through Braintree's official ID conversion. Conversion does not prove existence; retrieve the result before correcting it.

    View source on GitHub
  • braintree.retry_subscription script high High — service-affecting

    Retry a past-due subscription

    Collect exactly the current positive past-due balance and submit it for settlement. Braintree clears the entire outstanding balance after a successful retry; this action refuses a reduced amount. The read precondition is not atomic with the charge.

    View source on GitHub
  • braintree.set_subscription_payment_method script high High — service-affecting

    Replace a subscription payment method

    Replace the subscription's payment method with another method belonging to the same customer; proration is disabled. Does not charge it.

    View source on GitHub
  • braintree.set_subscription_price script high High — service-affecting

    Correct a subscription price

    Set the approved subscription price with proration disabled, preserving its plan association. Does not retroactively correct existing transactions.

    View source on GitHub
  • braintree.stage_dispute_text script high High — service-affecting

    Stage dispute text evidence

    Add one categorized text evidence item without finalizing the dispute. GraphQL supports the published card-dispute categories; PayPal EVIDENCE_TYPE and sequence-number evidence require the provider control panel.

    View source on GitHub
  • braintree.submit_dispute_evidence script high High — service-affecting

    Submit staged dispute evidence

    Finalize an open dispute and submit its evidence to the processor. Verifies the observed evidence inventory hash; the provider does not offer an atomic compare-and-submit.

    View source on GitHub
  • braintree.subscription script low Low — read-only or trivially reversible

    Show subscription

    Show one Braintree subscription with diagnostic state and billing linkage. Includes current price, outstanding balance, failure count and billing timeline; merchant_account_id identifies the processing currency. Nested arrays return at most ten entries with explicit overflow flags.

    View source on GitHub
  • braintree.subscription_transactions script low Low — read-only or trivially reversible

    List transaction IDs for one subscription

    List one local page of transaction IDs for one subscription. The provider returns an array; offset continues it without silently dropping entries.

    View source on GitHub
  • braintree.subscriptions script low Low — read-only or trivially reversible

    Search subscriptions

    List one bounded page of Braintree subscriptions matching the supplied criteria. Blank optional criteria intentionally impose no filter; returned cursors continue the same search.

    View source on GitHub
  • braintree.transaction script low Low — read-only or trivially reversible

    Show transaction

    Show one Braintree transaction with diagnostic state and billing linkage. Includes authorization/settlement codes, AVS/CVV results, refunds, disputes and disbursement details. Nested arrays return at most ten entries with explicit overflow flags.

    View source on GitHub
  • braintree.transaction_history script low Low — read-only or trivially reversible

    List status history for one transaction

    List one local page of status history for one transaction. The provider returns an array; offset continues it without silently dropping entries.

    View source on GitHub
  • braintree.transaction_refunds script low Low — read-only or trivially reversible

    List refunds for one transaction

    List one local page of refunds for one transaction. The provider returns an array; offset continues it without silently dropping entries.

    View source on GitHub
  • braintree.transactions script low Low — read-only or trivially reversible

    Search transactions

    List one bounded page of Braintree transactions matching the supplied criteria. Blank optional criteria intentionally impose no filter; returned cursors continue the same search.

    View source on GitHub
  • braintree.upload_dispute_file script high High — service-affecting

    Stage a dispute evidence file

    Upload one reviewed PDF, PNG, or JPEG of at most 4 MB and attach it to the dispute; does not finalize evidence.

    View source on GitHub
  • braintree.void_transaction script high High — service-affecting

    Void a transaction

    Void one eligible authorization or unsettled transaction. This is distinct from refunding a settled payment.

    View source on GitHub
← Back to registry
Pack reference  Publish your own