Package com.tnsai.tools.fintech

Class CashAppPayTools

java.lang.Object

com.tnsai.tools.fintech.CashAppPayTools

public class CashAppPayTools
extends Object

Function-shape Cash App Pay tools — the LangChain-style replacement for the legacy CashAppPayTool that returned simulated responses. This POJO makes real Cash App Pay customer-request/v1 API calls (see https://developers.cash.app/docs).

Three typed @Tool methods:

Method	Endpoint	Idempotent
cashappCreateRequest(long, java.lang.String, java.lang.String, java.lang.String, java.lang.String)	POST /customer-request	✓ (idempotency_key)
cashappGetRequest(java.lang.String)	GET /customer-request/{id}	✓
cashappCancelRequest(java.lang.String)	POST /customer-request/{id}/cancel	✓

Auth

Cash App Pay uses OAuth2; the consumer is responsible for obtaining the bearer access token (typically via Cash App's web auth flow against the configured CASHAPP_CLIENT_ID + CASHAPP_CLIENT_SECRET) and providing it to this POJO. Storing client credentials in this tool would force every agent dispatch to mint a new token, which is wasteful and racy. Treat the access token like any other short-lived secret — your auth layer refreshes it, the POJO consumes it.

Sandbox

Cash App's sandbox host is sandbox.api.cash.app. Set useSandbox=true (or CASHAPP_SANDBOX=true env) to route there during development. Always develop against sandbox.

Since:

0.5.7 (Phase 2 batch 7b — built-in tool migration to function shape, see #188)

Constructor Summary

Constructors

Constructor	Description
CashAppPayTools()	Default constructor — reads CASHAPP_ACCESS_TOKEN + CASHAPP_SANDBOX from env.
CashAppPayTools(String accessToken, boolean useSandbox)	Explicit token + sandbox flag.
CashAppPayTools(String accessToken, boolean useSandbox, okhttp3.OkHttpClient http, com.fasterxml.jackson.databind.ObjectMapper mapper)	Full constructor for tests / shared HTTP.

Method Summary

Modifier and Type	Method	Description
Map<String,Object>	cashappCancelRequest(String requestId)
Map<String,Object>	cashappCreateRequest(long amountCents, String currency, String note, String redirectUrl, String referenceId)
Map<String,Object>	cashappGetRequest(String requestId)

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

CashAppPayTools

public CashAppPayTools()

Default constructor — reads CASHAPP_ACCESS_TOKEN + CASHAPP_SANDBOX from env.

CashAppPayTools

public CashAppPayTools(String accessToken,
 boolean useSandbox)

Explicit token + sandbox flag.

CashAppPayTools

public CashAppPayTools(String accessToken,
 boolean useSandbox,
 okhttp3.OkHttpClient http,
 com.fasterxml.jackson.databind.ObjectMapper mapper)

Full constructor for tests / shared HTTP.

Method Details

cashappCreateRequest

@Tool(name="cashapp_create_request",
      description="DESTRUCTIVE: create a Cash App Pay customer payment request. {amountCents} is the amount in the smallest currency unit (1000 = $10.00 USD). Returns the request id, redirect URL the customer can pay via, and the QR-code URL the merchant can display in person. The call uses an idempotency_key (UUID per call) so transient retries do not duplicate the request.",
      keywords={"cashapp","cash-app","p2p","payment","request","fintech","block"},
      idempotent=true)
public Map<String,Object> cashappCreateRequest(@ToolParam(description="Amount in smallest currency unit (cents for USD; 1000 = $10.00)")
 long amountCents,
 @ToolParam(description="ISO 4217 currency code (Cash App is USD-only as of 2024-10; left for forward compat)",required=false,defaultValue="USD")
 String currency,
 @ToolParam(description="Note shown to the customer in the Cash App UI",required=false,defaultValue="")
 String note,
 @ToolParam(description="URL Cash App redirects to after the customer pays/cancels (deep link or web URL)",required=false,defaultValue="")
 String redirectUrl,
 @ToolParam(description="Merchant-side reference id (order number, invoice id); auto-generated UUID if blank",required=false,defaultValue="")
 String referenceId)
                                        throws IOException

Throws:

IOException

cashappGetRequest

@Tool(name="cashapp_get_request",
      description="Read the current state of a Cash App Pay customer request \u2014 read-only. Returns {id, referenceId, status, amount, currency} where status \u2208 {PENDING, APPROVED, DECLINED, COMPLETED, CANCELED}. Use this to poll the status of a request created via cashapp_create_request.",
      keywords={"cashapp","cash-app","request","status","poll"},
      idempotent=true)
public Map<String,Object> cashappGetRequest(@ToolParam(description="Request id returned by cashapp_create_request")
 String requestId)
                                     throws IOException

Throws:

IOException

cashappCancelRequest

@Tool(name="cashapp_cancel_request",
      description="DESTRUCTIVE: cancel a pending Cash App Pay customer request. After cancellation the customer can no longer pay against the request. Returns the updated {id, status: CANCELED} confirmation. Idempotent \u2014 cancelling an already-cancelled request returns the same payload (Cash App treats it as a no-op).",
      keywords={"cashapp","cash-app","cancel","request"},
      idempotent=true)
public Map<String,Object> cashappCancelRequest(@ToolParam(description="Request id returned by cashapp_create_request")
 String requestId)
                                        throws IOException

Throws:

IOException