Worlds / Payments and billing

PayPal Braintree API

A local Braintree with transactions, vaulted payment methods, customers, disputes and settlement batches. Test the agent that voids, refunds and handles disputes based on settlement status.

Base path: /graphql
Auth: Basic auth with public and private keys, the world key
Endpoints: 15
Status: Active today

This reference previews the surface the PayPal Braintree world serves in the closed beta. Paths mirror the public PayPal Braintree API; the exact subset is confirmed when your workflow is scoped.

Connect

The run gives your agent these bindings. Keep your SDK; change only where it sends requests.

binding	meaning
`WORLDS_BRAINTREE_URL`	This world's origin followed by `/graphql`
`WORLDS_API_KEY`	The world key, accepted wherever PayPal Braintree expects a credential
`WORLDS_WORLD_ID`	The isolated world's identity

js · braintree

import braintree from "braintree";

const gateway = new braintree.BraintreeGateway({
  environment: braintree.Environment.Sandbox,
  merchantId: "merchant",
  publicKey: "public",
  privateKey: process.env.WORLDS_API_KEY,
});
gateway.config.baseUrl = process.env.WORLDS_BRAINTREE_URL;

const result = await gateway.transaction.refund("txn_123", "5.00");

API reference

15 of 15

Transactions

Charges, voids and refunds.

POST/graphql/graphql · chargePaymentMethodCharge a payment method
POST/graphql/graphql · captureTransactionCapture an authorized transaction
POST/graphql/graphql · reverseTransactionVoid a transaction
POST/graphql/graphql · refundTransactionRefund a settled transaction
POST/graphql/graphql · searchSearch transactions

Fields · 5

`id`	string	Transaction id
`amount`	string	Decimal amount
`status`	string	authorized, settled, voided and more
`customer`	object	Customer details
`paymentMethod`	object	Card or wallet used

Customers

Stored customer profiles.

POST/graphql/graphql · createCustomerCreate a customer
POST/graphql/graphql · updateCustomerUpdate a customer
POST/graphql/graphql · deleteCustomerDelete a customer
POST/graphql/graphql · customerFetch a customer

Fields · 4

`id`	string	Customer id
`email`	string	Email address
`firstName`	string	First name
`lastName`	string	Last name

Payment methods

Vaulted cards and wallets.

POST/graphql/graphql · tokenizeCreditCardTokenize a card
POST/graphql/graphql · vaultPaymentMethodVault a payment method
POST/graphql/graphql · deletePaymentMethodFromVaultRemove a vaulted method

Fields · 4

`id`	string	Payment method id
`usage`	string	SINGLE_USE or MULTI_USE
`details`	object	Brand, last four, expiry
`customer`	object	Owning customer

Disputes

Chargebacks raised against transactions.

POST/graphql/graphql · searchSearch disputes
POST/graphql/graphql · addDisputeTextEvidenceAdd text evidence to a dispute
POST/graphql/graphql · acceptDisputeAccept a dispute

Fields · 4

`id`	string	Dispute id
`amountDisputed`	object	Disputed amount
`status`	string	OPEN, WON or LOST
`reasonCode`	string	Card network reason code

Test workflow

Prepare. Select the PayPal Braintree setup for your workflow and review its starting records, including transactions, customers, payment methods.
Connect. Configure your agent with this world's URL and key using the SDK example. Check that it reaches the intended API before running a test.
Define. Describe the task, expected final changes and records that must stay untouched. Keep expected outcomes separate from the agent's instructions.
Run and inspect. Use the dashboard or your workflow's generated CLI setup. Review final records and changes, then rerun from the same starting setup with the relevant failure conditions. Use Deployment and CI to automate the same workflow.

What to verify

8k2m4p voided, not refunded
3d9q2r refunded once for $210.00
5h1n8w untouched because dispute dp_44 is open
No refund issued on 9a7x1c, the original charge
No new transactions created on any customer

Test file

A task file names the jobs, the policy your agent is given and what the grader reads back from the world's final state. The agent never sees the expected outcomes.

yaml · worlds/tasks.yaml

# worlds/tasks.yaml · PayPal Braintree
version: 2
connector: braintree
seed: braintree-starter
mode: isolated
policy: >
  Clean up the double charges from Tuesday. Void the duplicate if it has not
  settled, refund it if it has. Do not refund anything with an open dispute.
tasks:
  - id: void-unsettled-transactions-and-refund-settled-ones
    prompt: Void unsettled transactions and refund settled ones
  - id: update-a-vaulted-card-for-a-customer
    prompt: Update a vaulted card for a customer
  - id: accept-or-submit-evidence-on-a-dispute
    prompt: Accept or submit evidence on a dispute
expected:
  - "8k2m4p voided, not refunded"
  - 3d9q2r refunded once for $210.00
  - 5h1n8w untouched because dispute dp_44 is open
  - "No refund issued on 9a7x1c, the original charge"
  - No new transactions created on any customer
scenarios:
  - not-settled
  - processor-declined
  - gateway-rejected

See Tasks and outcomes for every field, and Deployment and CI to run the file on every pull request.

Failure conditions

Each one fires before the handler, at the same step on every run.

condition	what the agent sees
`not-settled`	Refund returns error 91506, cannot refund unless settled
`processor-declined`	A retry returns processor response 2001 Insufficient Funds
`gateway-rejected`	A charge is gateway_rejected with reason duplicate
`webhook`	dispute_opened arrives for a transaction already refunded
`rate-limited`	The GraphQL API returns 429 on bulk search

Starting data

Start each run from the same records and relationships. The overview below describes the PayPal Braintree starter; use the setup supplied for your workflow when preparing your own snapshot.

Records	Starting setup
transactions	160 across authorized, submitted_for_settlement, settled and processor_declined
customers	70 with vaulted payment method tokens
disputes	5 open, 2 won, 1 lost
subscriptions	30 on monthly plans, 3 past due

The record shapes below reuse this world's API field definitions. They show illustrative values and placeholders, not an importable seed. API responses and seed input can differ; include all required records and references in the accepted import format for your workflow.

Transactions records

Transactions

Charges, voids and refunds.

Field	Type	Meaning / relationship
`id`	string	Transaction id
`amount`	string	Decimal amount
`status`	string	authorized, settled, voided and more
`customer`	object	Customer details
`paymentMethod`	object	Card or wallet used

json · illustrative record shape

{
  "id": "<Transaction id>",
  "amount": "<Decimal amount>",
  "status": "<authorized, settled, voided and more>",
  "customer": {},
  "paymentMethod": {}
}

See transactions operations

Customers records

Customers

Stored customer profiles.

Field	Type	Meaning / relationship
`id`	string	Customer id
`email`	string	Email address
`firstName`	string	First name
`lastName`	string	Last name

json · illustrative record shape

{
  "id": "<Customer id>",
  "email": "person@example.test",
  "firstName": "<First name>",
  "lastName": "<Last name>"
}

See customers operations

Payment methods records

Payment methods

Vaulted cards and wallets.

Field	Type	Meaning / relationship
`id`	string	Payment method id
`usage`	string	SINGLE_USE or MULTI_USE
`details`	object	Brand, last four, expiry
`customer`	object	Owning customer

json · illustrative record shape

{
  "id": "<Payment method id>",
  "usage": "<SINGLE_USE or MULTI_USE>",
  "details": {},
  "customer": {}
}

See payment methods operations

Disputes records

Disputes

Chargebacks raised against transactions.

Field	Type	Meaning / relationship
`id`	string	Dispute id
`amountDisputed`	object	Disputed amount
`status`	string	OPEN, WON or LOST
`reasonCode`	string	Card network reason code

json · illustrative record shape

{
  "id": "<Dispute id>",
  "amountDisputed": {},
  "status": "<OPEN, WON or LOST>",
  "reasonCode": "<Card network reason code>"
}

See disputes operations

See the PayPal Braintree world in the catalog