Cash App

App · 25 actions

Manage Cash App Pay brands, merchants, customer grants, payments, refunds and disputes.

Actions

ActionWhat it does
Capture paymentSet the final amount of an authorized payment and complete it, so it is paid out in the next nightly settlement.
Capture refundComplete a refund, so it is paid out in the next nightly settlement.
Create brandCreate a brand.
Create merchantCreate a merchant.
Create paymentCreate a payment from a customer to a merchant.
Create refundCreate a refund from a merchant to a customer.
Get balanceGet one balance by its ID.
Get brandGet one brand by its ID.
Get customerGet one customer by their ID.
Get customer grantGet one customer grant, by the ID of the customer who approved it and the grant's own ID.
Get merchantGet one merchant by its ID.
Get paymentGet one payment by its ID.
Get refundGet one refund by its ID.
List balancesList balances, optionally filtered by customer, grant or type.
List brandsList brands, optionally filtered by reference ID.
List customer grantsList a customer's grants.
List customersList the customers who have ever allowed you to take actions on their Cash App account, optionally filtered by cashtag.
List disputesList the disputes on your payments, optionally for one merchant.
List merchantsList merchants, optionally filtered by reference ID.
List paymentsList payments, optionally filtered by customer, merchant or reference ID.
List refundsList refunds, optionally filtered by customer, merchant or reference ID.
Update brandUpdate a brand.
Update merchantUpdate a merchant.
Void paymentVoid an authorized payment, releasing the hold on the customer's Cash App account.
Void refundVoid an authorized refund, removing the pending refund from the customer's Cash App account.

Capture payment

Set the final amount of an authorized payment and complete it, so it is paid out in the next nightly settlement.

Inputs

Payment idpayment_idtextRequired
Payment id.
Idempotency keyidempotency_keytextRequired
A unique identifier which can be used by Cash App to de-duplicate retries of this request, making it idempotent. For more information, see Idempotency.
AmountamountnumberRequired
The amount of money to collect from the customer, in the lowest denomination of currency for the payment. To over-capture or under-capture the payment, set this field to a different value from the current payment amount. Min value: 1At least 1.

Outputs

dataobject
Cash App response data.
Example output
{
  "data": {
    "payment": {
      "amount": 1,
      "authorization_updates": [],
      "capture_before": "example",
      "captured_amount": 1,
      "created_at": "example",
      "currency": "USD",
      "customer_id": "example",
      "decline_errors": [],
      "enrichments": {
        "initiation": {
          "actor": "CUSTOMER"
        },
        "recurring_series_id": "example",
        "restricted_categories": [],
        "statement_descriptor": "example"
      },
      "fee_amount": 1.0,
      "fee_rate": {
        "basis_points": 1,
        "fixed_amount": 1
      },
      "grant_id": "example",
      "id": "example",
      "merchant_id": "example",
      "metadata": {},
      "net_amount": 1,
      "reference_id": "example",
      "refund_ids": [],
      "refunded_amount": 1,
      "status": "AUTHORIZED",
      "updated_at": "example",
      "voided_amount": 1
    }
  }
}

Capture refund

Complete a refund, so it is paid out in the next nightly settlement.

Inputs

Refund idrefund_idtextRequired
Refund id.
Idempotency keyidempotency_keytextRequired
A unique identifier which can be used by Cash App to de-duplicate retries of this request, making it idempotent. For more information, see Idempotency.

Outputs

dataobject
Cash App response data.
Example output
{
  "data": {
    "refund": {
      "amount": 1,
      "created_at": "example",
      "currency": "USD",
      "customer_id": "example",
      "decline_errors": [],
      "grant_id": "example",
      "id": "example",
      "merchant_id": "example",
      "metadata": {},
      "payment_id": "example",
      "reference_id": "example",
      "status": "AUTHORIZED",
      "updated_at": "example"
    }
  }
}

Create brand

Create a brand.

Inputs

Idempotency keyidempotency_keytextRequired
A unique identifier which can be used by Cash App to de-duplicate retries of this request, making it idempotent. For more information, see Idempotency.
BrandbrandobjectRequired
Details about the brand to create.

Outputs

dataobject
Cash App response data.
Example output
{
  "data": {
    "brand": {
      "color": "example",
      "created_at": "example",
      "id": "example",
      "metadata": {},
      "name": "example",
      "profile_image_url": "example",
      "reference_id": "example",
      "updated_at": "example"
    }
  }
}

Create merchant

Create a merchant. A merchant needs an address or a website URL.

Inputs

Idempotency keyidempotency_keytextRequired
A unique identifier which can be used by Cash App to de-duplicate retries of this request, making it idempotent. For more information, see Idempotency.
MerchantmerchantobjectRequired
Details about the merchant to create.

Outputs

dataobject
Cash App response data.
Example output
{
  "data": {
    "merchant": {
      "address": {
        "address_line_1": "example",
        "address_line_2": "example",
        "administrative_district_level_1": "example",
        "country": "US",
        "locality": "example",
        "postal_code": "example"
      },
      "brand_id": "example",
      "category": "example",
      "country": "US",
      "created_at": "example",
      "currency": "USD",
      "default_fee_plans": {
        "in_app_fee_plan_id": "example",
        "in_person_fee_plan_id": "example",
        "online_fee_plan_id": "example"
      },
      "id": "example",
      "metadata": {},
      "name": "example",
      "reference_id": "example",
      "site_url": "example",
      "status": "ACTIVE",
      "updated_at": "example"
    }
  }
}

Create payment

Create a payment from a customer to a merchant.

Inputs

Idempotency keyidempotency_keytextRequired
A unique identifier which can be used by Cash App to de-duplicate retries of this request, making it idempotent. For more information, see Idempotency.
PaymentpaymentobjectRequired
Data about the payment to create.

Outputs

dataobject
Cash App response data.
Example output
{
  "data": {
    "payment": {
      "amount": 1,
      "authorization_updates": [],
      "capture_before": "example",
      "captured_amount": 1,
      "created_at": "example",
      "currency": "USD",
      "customer_id": "example",
      "decline_errors": [],
      "enrichments": {
        "initiation": {
          "actor": "CUSTOMER"
        },
        "recurring_series_id": "example",
        "restricted_categories": [],
        "statement_descriptor": "example"
      },
      "fee_amount": 1.0,
      "fee_rate": {
        "basis_points": 1,
        "fixed_amount": 1
      },
      "grant_id": "example",
      "id": "example",
      "merchant_id": "example",
      "metadata": {},
      "net_amount": 1,
      "reference_id": "example",
      "refund_ids": [],
      "refunded_amount": 1,
      "status": "AUTHORIZED",
      "updated_at": "example",
      "voided_amount": 1
    }
  }
}

Create refund

Create a refund from a merchant to a customer.

Inputs

Idempotency keyidempotency_keytextRequired
A unique identifier which can be used by Cash App to de-duplicate retries of this request, making it idempotent. For more information, see Idempotency.
RefundrefundobjectRequired
Details about the refund to create.

Outputs

dataobject
Cash App response data.
Example output
{
  "data": {
    "refund": {
      "amount": 1,
      "created_at": "example",
      "currency": "USD",
      "customer_id": "example",
      "decline_errors": [],
      "grant_id": "example",
      "id": "example",
      "merchant_id": "example",
      "metadata": {},
      "payment_id": "example",
      "reference_id": "example",
      "status": "AUTHORIZED",
      "updated_at": "example"
    }
  }
}

Get balance

Get one balance by its ID.

Inputs

Balance idbalance_idtextRequired
Balance id.
Grant idgrant_idtext
Grant id.

Outputs

dataobject
Cash App response data.
Example output
{
  "data": {
    "balance": {
      "amount": 1,
      "created_at": "example",
      "currency": "USD",
      "customer_id": "example",
      "id": "example",
      "type": "CHECKING",
      "updated_at": "example"
    }
  }
}

Get brand

Get one brand by its ID.

Inputs

Brand idbrand_idtextRequired
Brand id.

Outputs

dataobject
Cash App response data.
Example output
{
  "data": {
    "brand": {
      "color": "example",
      "created_at": "example",
      "id": "example",
      "metadata": {},
      "name": "example",
      "profile_image_url": "example",
      "reference_id": "example",
      "updated_at": "example"
    }
  }
}

Get customer

Get one customer by their ID.

Inputs

Customer idcustomer_idtextRequired
Customer id.

Outputs

dataobject
Cash App response data.
Example output
{
  "data": {
    "customer": {
      "cashtag": "example",
      "id": "example",
      "reference_id": "example"
    }
  }
}

Get customer grant

Get one customer grant, by the ID of the customer who approved it and the grant's own ID.

Inputs

Customer idcustomer_idtextRequired
Customer id.
Grant idgrant_idtextRequired
Grant id.

Outputs

dataobject
Cash App response data.
Example output
{
  "data": {
    "grant": {
      "action": {},
      "channel": "IN_PERSON",
      "created_at": "example",
      "customer_id": "example",
      "expires_at": "example",
      "id": "example",
      "request_id": "example",
      "status": "ACTIVE",
      "type": "ONE_TIME",
      "updated_at": "example"
    }
  }
}

Get merchant

Get one merchant by its ID.

Inputs

Merchant idmerchant_idtextRequired
Merchant id.

Outputs

dataobject
Cash App response data.
Example output
{
  "data": {
    "merchant": {
      "address": {
        "address_line_1": "example",
        "address_line_2": "example",
        "administrative_district_level_1": "example",
        "country": "US",
        "locality": "example",
        "postal_code": "example"
      },
      "brand_id": "example",
      "category": "example",
      "country": "US",
      "created_at": "example",
      "currency": "USD",
      "default_fee_plans": {
        "in_app_fee_plan_id": "example",
        "in_person_fee_plan_id": "example",
        "online_fee_plan_id": "example"
      },
      "id": "example",
      "metadata": {},
      "name": "example",
      "reference_id": "example",
      "site_url": "example",
      "status": "ACTIVE",
      "updated_at": "example"
    }
  }
}

Get payment

Get one payment by its ID.

Inputs

Payment idpayment_idtextRequired
Payment id.

Outputs

dataobject
Cash App response data.
Example output
{
  "data": {
    "payment": {
      "amount": 1,
      "authorization_updates": [],
      "capture_before": "example",
      "captured_amount": 1,
      "created_at": "example",
      "currency": "USD",
      "customer_id": "example",
      "decline_errors": [],
      "enrichments": {
        "initiation": {
          "actor": "CUSTOMER"
        },
        "recurring_series_id": "example",
        "restricted_categories": [],
        "statement_descriptor": "example"
      },
      "fee_amount": 1.0,
      "fee_rate": {
        "basis_points": 1,
        "fixed_amount": 1
      },
      "grant_id": "example",
      "id": "example",
      "merchant_id": "example",
      "metadata": {},
      "net_amount": 1,
      "reference_id": "example",
      "refund_ids": [],
      "refunded_amount": 1,
      "status": "AUTHORIZED",
      "updated_at": "example",
      "voided_amount": 1
    }
  }
}

Get refund

Get one refund by its ID.

Inputs

Refund idrefund_idtextRequired
Refund id.

Outputs

dataobject
Cash App response data.
Example output
{
  "data": {
    "refund": {
      "amount": 1,
      "created_at": "example",
      "currency": "USD",
      "customer_id": "example",
      "decline_errors": [],
      "grant_id": "example",
      "id": "example",
      "merchant_id": "example",
      "metadata": {},
      "payment_id": "example",
      "reference_id": "example",
      "status": "AUTHORIZED",
      "updated_at": "example"
    }
  }
}

List balances

List balances, optionally filtered by customer, grant or type.

Inputs

Customer idcustomer_idtextRequired
Customer id.
TypetypetextRequired
Type.One of: CHECKING.
Grant idgrant_idtext
Grant id.
Cursorcursortext
Cursor.
Limitlimitnumber
Limit.From 1 to 100. Default: 50.

Outputs

dataobject
Cash App response data.
Example output
{
  "data": {
    "balances": [],
    "cursor": "example"
  }
}

List brands

List brands, optionally filtered by reference ID.

Inputs

Cursorcursortext
Cursor.
Limitlimitnumber
Limit.From 1 to 100. Default: 50.
Reference idreference_idtext
Reference id.

Outputs

dataobject
Cash App response data.
Example output
{
  "data": {
    "brands": [],
    "cursor": "example"
  }
}

List customer grants

List a customer's grants.

Inputs

Customer idcustomer_idtextRequired
Customer id.
Cursorcursortext
Cursor.
Limitlimitnumber
Limit.From 1 to 100. Default: 50.

Outputs

dataobject
Cash App response data.
Example output
{
  "data": {
    "cursor": "example",
    "grants": []
  }
}

List customers

List the customers who have ever allowed you to take actions on their Cash App account, optionally filtered by cashtag.

Inputs

Cursorcursortext
Cursor.
Limitlimitnumber
Limit.From 1 to 100. Default: 50.
Cashtagcashtagtext
Cashtag.

Outputs

dataobject
Cash App response data.
Example output
{
  "data": {
    "cursor": "example",
    "customers": []
  }
}

List disputes

List the disputes on your payments, optionally for one merchant.

Inputs

Cursorcursortext
Cursor.
Limitlimitnumber
Limit.From 1 to 100. Default: 50.
Merchant idmerchant_idtext
Merchant id.

Outputs

dataobject
Cash App response data.
Example output
{
  "data": {
    "cursor": "example",
    "disputes": []
  }
}

List merchants

List merchants, optionally filtered by reference ID.

Inputs

Reference idreference_idtext
Reference id.
Cursorcursortext
Cursor.
Limitlimitnumber
Limit.From 1 to 100. Default: 50.

Outputs

dataobject
Cash App response data.
Example output
{
  "data": {
    "cursor": "example",
    "merchants": []
  }
}

List payments

List payments, optionally filtered by customer, merchant or reference ID.

Inputs

Cursorcursortext
Cursor.
Reference idreference_idtext
Reference id.
Customer idcustomer_idtext
Customer id.
Merchant idmerchant_idtext
Merchant id.
Limitlimitnumber
Limit.From 1 to 100. Default: 50.

Outputs

dataobject
Cash App response data.
Example output
{
  "data": {
    "cursor": "example",
    "payments": []
  }
}

List refunds

List refunds, optionally filtered by customer, merchant or reference ID.

Inputs

Cursorcursortext
Cursor.
Reference idreference_idtext
Reference id.
Customer idcustomer_idtext
Customer id.
Merchant idmerchant_idtext
Merchant id.
Limitlimitnumber
Limit.From 1 to 100. Default: 50.

Outputs

dataobject
Cash App response data.
Example output
{
  "data": {
    "cursor": "example",
    "refunds": []
  }
}

Update brand

Update a brand.

Inputs

Brand idbrand_idtextRequired
Brand id.
BrandbrandobjectRequired
Details about the brand to update

Outputs

dataobject
Cash App response data.
Example output
{
  "data": {
    "brand": {
      "color": "example",
      "created_at": "example",
      "id": "example",
      "metadata": {},
      "name": "example",
      "profile_image_url": "example",
      "reference_id": "example",
      "updated_at": "example"
    }
  }
}

Update merchant

Update a merchant.

Inputs

Merchant idmerchant_idtextRequired
Merchant id.
MerchantmerchantobjectRequired
Details about the merchant to update.

Outputs

dataobject
Cash App response data.
Example output
{
  "data": {
    "merchant": {
      "address": {
        "address_line_1": "example",
        "address_line_2": "example",
        "administrative_district_level_1": "example",
        "country": "US",
        "locality": "example",
        "postal_code": "example"
      },
      "brand_id": "example",
      "category": "example",
      "country": "US",
      "created_at": "example",
      "currency": "USD",
      "default_fee_plans": {
        "in_app_fee_plan_id": "example",
        "in_person_fee_plan_id": "example",
        "online_fee_plan_id": "example"
      },
      "id": "example",
      "metadata": {},
      "name": "example",
      "reference_id": "example",
      "site_url": "example",
      "status": "ACTIVE",
      "updated_at": "example"
    }
  }
}

Void payment

Void an authorized payment, releasing the hold on the customer's Cash App account.

Inputs

Payment idpayment_idtextRequired
Payment id.

Outputs

dataobject
Cash App response data.
Example output
{
  "data": {
    "payment": {
      "amount": 1,
      "authorization_updates": [],
      "capture_before": "example",
      "captured_amount": 1,
      "created_at": "example",
      "currency": "USD",
      "customer_id": "example",
      "decline_errors": [],
      "enrichments": {
        "initiation": {
          "actor": "CUSTOMER"
        },
        "recurring_series_id": "example",
        "restricted_categories": [],
        "statement_descriptor": "example"
      },
      "fee_amount": 1.0,
      "fee_rate": {
        "basis_points": 1,
        "fixed_amount": 1
      },
      "grant_id": "example",
      "id": "example",
      "merchant_id": "example",
      "metadata": {},
      "net_amount": 1,
      "reference_id": "example",
      "refund_ids": [],
      "refunded_amount": 1,
      "status": "AUTHORIZED",
      "updated_at": "example",
      "voided_amount": 1
    }
  }
}

Void refund

Void an authorized refund, removing the pending refund from the customer's Cash App account.

Inputs

Refund idrefund_idtextRequired
Refund id.

Outputs

dataobject
Cash App response data.
Example output
{
  "data": {
    "refund": {
      "amount": 1,
      "created_at": "example",
      "currency": "USD",
      "customer_id": "example",
      "decline_errors": [],
      "grant_id": "example",
      "id": "example",
      "merchant_id": "example",
      "metadata": {},
      "payment_id": "example",
      "reference_id": "example",
      "status": "AUTHORIZED",
      "updated_at": "example"
    }
  }
}

On this page